\n The project directory
\nA typical Urubu project directory looks as follows:
\nMakefile\n_site.yml\n_layouts/_base.html\n page.html\n ...\n_python/__init__.py\n validators.py\n filters.py\ncss/...\njs/...\nindex.md\nfolder1/index.md\n file1.md\n pic1.png\n ...\nfolder2/index.md\n file2.md\n file3.md\n ...\n
Files and directories with pathnames starting with an underscore _ are\nspecial. They are used during processing, but excluded from the built website.\nTheir function will be discussed below.
\nThe css and js directories are just an example of how CSS style sheets and\njavascript files could be organized. You can use any organization that you\nprefer.
\nContent files are in Markdown format and should have the .md extension. You\nhave complete freedom in organizing them in directories. However, every\ndirectory should have an index.md file, including the top-level directory.
\nProcessing rules
\nUrubu generates a website by processing the files and directory in the project\ndirectory, and putting the result in a _build subdirectory. The processing\ndepends on the pathname as follows:
\n\n- \n
a Makefile is ignored and not copied to the build.
\n \n- \n
files and directories starting with a dot . or\nunderscore _ are ignored and not copied to the build.
\n \n- \n
Markdown files with extension .md are converted to a\nhtml file that is put into the build in the same relative location.
\n \n- \n
all other files and directories are copied unmodified to the build in the\nsame relative location.
\n \n
\nAs a result of the project organization and the build process, the structure of\nthe build matches the structure of the project directory. The relative\nlocation of all files is thus preserved.
\nSpecial files and directories
\n_site.yml
\nThis file contains site configuration info in YAML format.\nCurrently, these are the predefined attributes:
\n\n\n\n| Attribute | \nDescription | \n
\n\n\n\nreflinks | \nHolds a mapping from reference ids to link objects. | \n
\n\nbaseurl | \nPrefix for generated local URLs | \n
\n\nfile_ext | \nChange default file extension ('.html') for processed .md files | \n
\n\nlink_ext | \nChange default file extension ('.html') for links to site's pages | \n
\n\nignore_patterns | \nList of additional file names or globs to be ignored during processing | \n
\n\nkeep_files | \nList of explicit file names be kept, overriding any ignores | \n
\n\nstrict_undefined | \nSet the default behavior regarding undefined template variables | \n
\n\n
\nLink objects, for the reflinks attribute, are a mapping with an url key that maps\nto the link URL and a title key that maps to the link title.
\nThe baseurl option mirrors the same feature in Jekyll. It\nallows you to specify a prefix for all local URLs generated within your site.\nThis is necessary when your site will be served from a URL that has more than\njust the hostname. For example, on GitHub Pages sites are served from\nhttp://username.github.io/project_name/, so Urubu needs to include that\n/project_name/ in generated URLs pointing to local content.
\nbaseurl should be specified with no beginning or trailing slashes, e.g.:
\n\n\nThe file extension attributes, file_ext and link_ext, are both usually set to the\nsame value (i.e. '.php'), unless the target site has .htaccess rewrite rules that\naffect the file extensions.
\nExamples of this are sites that internally redirect pages like www.test.com/account\nto www.test.com/account.htm. For this case, one would need to set file_ext to\n'.htm', so Urubu generated files have the .htm extension, whereas link_ext would\nbe set to '', so that the a href links are directed to the files without extension.
\nOtherwise, file_ext and link_ext should be set to the same extension, specially\nduring testing, so that the simple web server invoked by urubu serve works fine,\nas well as any web server that does not rewrite the file extensions of the requests.
\nThe ignore_patterns attribute specifies glob-style patterns to be ignored\nduring processing, in addition to the default ones according to the\nProcessing Rules.
\nIn some cases you may explicitly want to keep certain files that would normally\nbe ignored. For example, you may have hidden files like .nojekyll to prevent\nJekyll processing, or .htaccess and .htpasswd for access control. You can\nkeep such files in the build using the keep_files attribute.
\nThe strict_undefined attribute controls whether the build should\nsilently ignore undefined template variables or raise an error when they are\nencountered. If false or undefined, undefined template variables are treated\nas empty strings (''). If true, the build will stop and raise an error.
\nYou can define additional attributes that will be made available as\nsite variables to the template engine. The following is an example of a\n_site.yml file:
\nbrand: Urubu\n\nreflinks:\n content_license:\n url: http://creativecommons.org/licenses/by-sa/3.0/\n title: CC-BY-SA License\n software_license:\n url: http://www.gnu.org/licenses/agpl-3.0.txt\n title: GNU Affero General Public License\n markdown:\n url: http://daringfireball.net/projects/markdown/\n title: Markdown\n\nfile_ext: '.htm' # Change default file extension ('.html')\nlink_ext: '.htm' # Change default link extension ('.html')\n
_layouts
\nThis directory contains the available layouts.\nThey are used by the Jinja2 template engine to render html pages.\nThe layout files should have the .html extension.
\n_python
\nThis directory contains Python hooks for the template engine.
\nProject-wide reference ids
\nUrubu has the concept of project-wide reference ids. You can use them to refer\nto link objects in your content and configuration. Their definition comes\nfrom two sources:
\n\n- global reference ids are mapped to link objects in the
_site.yml\nconfiguration file, as discussed earlier. \n- all content pages and folders objects have reference ids.
\n
\nProject-wide references ids live in a single namespace. For pages and folders,\nthe id is a root-relative pathname starting with a slash / and without file\nextension. By convention, global reference ids should not start with a /.
\nIn your content and configuration info, you can also use relative reference\nids. Urubu will resolve them depending on the file location in the project. In\ncase of a name clash with a global reference id, you will have to disambiguate\nby adding pathname components.
\nIn accordance with Markdown conventions, reference ids are case-insensitive.
\nContent files
\nContent files are Markdown files with extension .md. They should start with\nYAML front matter that defines a number of attributes, as in the following example:
\n---\ntitle: Read me first\nlayout: page\ndate: 2014-01-15\n---\n<Markdown content>\n
The following attributes are predefined:
\n\n\n\n| Attribute | \nDescription | \n
\n\n\n\ntitle | \nSpecifies the page title. Mandatory. | \n
\n\nlayout | \nSpecifies the layout, without the .html extension, or null. Mandatory. | \n
\n\ndate | \nSpecifies the date in YYYY-MM-DD format. Optional. | \n
\n\ntags | \nA tag or list of tags for the content. | \n
\n\nsaveas | \nAllows overriding of the output filename. | \n
\n\n
\nThe layout attribute is mandatory, but can be given a null value.\nThis is useful when the page content is used by other pages, but\nno html output is required for the page itself.
\nIn addition, you can add arbitrary user-defined attributes. All attributes\nare made available as page object attributes to the template engine.
\nMarkdown in attributes
\nOptionally, you can use markdown format in front matter attributes. Markdown\nprocessing is enabled by adding a .md suffix to the attribute. The resulting\nhtml code will be stored in a synthesized attribute without the .md suffix.
\nFor example:
\n---\ntitle:\nlayout: page\nsummary.md: |\n A summary of the page items as a list:\n\n * item 1\n * item 2\n * item 3\n---\n
After processing, the page object will have a summary attribute with the html\ncode.
\nIndex files
\nIndex files with basename index.md are a special kind of content files. They\nare used to specify the attributes and the content of a directory. There are\ntwo options to specify the content, explicitly with the content attribute or\nimplicitly using the order attribute.
\n\n\n\n| Attribute | \nDescription | \n
\n\n\n\ncontent | \nDefines the content explicitly as a list of reference ids or local link objects. | \n
\n\norder | \nDefines the attribute by which the content in the directory should be ordered. | \n
\n\nreverse | \nOptional boolean attribute defines reverse order or not. Default is false. | \n
\n\n
\ncontent and order are mutually exclusive; you should use one of the two options.
\nA local link object is a mapping with either a url key to an url, or a ref\nkey to a reference id as mandatory items. In addtion, you can specify a title\nwith a title key.
\nThe ordering attribute can be predefined or user-defined, but it should be\nspecified in each content file in the directory. As an example, you can\nspecify that the content of a directory should be ordered as blog by the\nfollowing front matter in the index file:
\n---\ntitle: Blog\nlayout: blog_index\norder: date\nreverse: true\n---\n
Tag directory
\nThe optional top-level directory called tag has a predefined meaning. Urubu\nuses the corresponding folder in the build to hold the tag-related content view\nthat it generates automatically. You can use the index file to set attributes\nsuch as the layout. However, the content will be generated by Urubu\nautomatically and needs not be set.
\n ![\"An](\"/img/urubu.jpg\")
\n ![\\\"{{caption}}\\\"](\\\"/img/{{fn}}\\\")
\\n {% if caption %}\\n ![\"{{caption}}\"](\"/img/{{fn}}\")
\n {% if caption %}\n