The project directory
A typical Urubu project directory looks as follows:
Makefile _site.yml _layouts/_base.html page.html ... _python/__init__.py validators.py filters.py css/... js/... index.md folder1/index.md file1.md pic1.png ... folder2/index.md file2.md file3.md ...
Files and directories with pathnames starting with an underscore
special. They are used during processing, but excluded from the built website.
Their function will be discussed below.
js directories are just an example of how CSS style sheets and
Content files are in Markdown format and should have the
.md extension. You
have complete freedom in organizing them in directories. However, every
directory should have an
index.md file, including the top-level directory.
Urubu generates a website by processing the files and directory in the project
directory, and putting the result in a
_build subdirectory. The processing
depends on the pathname as follows:
Makefileis ignored and not copied to the build.
files and directories starting with a dot
_are ignored and not copied to the build.
Markdown files with extension
.mdare converted to a html file that is put into the build in the same relative location.
all other files and directories are copied unmodified to the build in the same relative location.
As a result of the project organization and the build process, the structure of the build matches the structure of the project directory. The relative location of all files is thus preserved.
Special files and directories
This file contains site configuration info in YAML format. Currently, these are the predefined attributes:
||Holds a mapping from reference ids to link objects.|
||Prefix for generated local URLs|
||Change default file extension (
||Change default file extension (
||List of additional file names or globs to be ignored during processing|
||List of explicit file names be kept, overriding any ignores|
||Set the default behavior regarding undefined template variables|
Link objects, for the
reflinks attribute, are a mapping with an
url key that maps
to the link URL and a
title key that maps to the link title.
baseurl option mirrors the same feature in Jekyll. It
allows you to specify a prefix for all local URLs generated within your site.
This is necessary when your site will be served from a URL that has more than
just the hostname. For example, on GitHub Pages sites are served from
http://username.github.io/project_name/, so Urubu needs to include that
/project_name/ in generated URLs pointing to local content.
baseurl should be specified with no beginning or trailing slashes, e.g.:
The file extension attributes,
link_ext, are both usually set to the
same value (i.e.
'.php'), unless the target site has .htaccess rewrite rules that
affect the file extensions.
Examples of this are sites that internally redirect pages like
www.test.com/account.htm. For this case, one would need to set
'.htm', so Urubu generated files have the
.htm extension, whereas
be set to
'', so that the
a href links are directed to the files without extension.
link_ext should be set to the same extension, specially
during testing, so that the simple web server invoked by
urubu serve works fine,
as well as any web server that does not rewrite the file extensions of the requests.
ignore_patterns attribute specifies glob-style patterns to be ignored
during processing, in addition to the default ones according to the
In some cases you may explicitly want to keep certain files that would normally
be ignored. For example, you may have hidden files like
.nojekyll to prevent
Jekyll processing, or
.htpasswd for access control. You can
keep such files in the build using the
strict_undefined attribute controls whether the build should
silently ignore undefined template variables or raise an error when they are
false or undefined, undefined template variables are treated
as empty strings (
true, the build will stop and raise an error.
You can define additional attributes that will be made available as
site variables to the template engine. The following is an example of a
brand: Urubu reflinks: content_license: url: http://creativecommons.org/licenses/by-sa/3.0/ title: CC-BY-SA License software_license: url: http://www.gnu.org/licenses/agpl-3.0.txt title: GNU Affero General Public License markdown: url: http://daringfireball.net/projects/markdown/ title: Markdown file_ext: '.htm' # Change default file extension ('.html') link_ext: '.htm' # Change default link extension ('.html')
This directory contains the available layouts.
They are used by the Jinja2 template engine to render html pages.
The layout files should have the
This directory contains Python hooks for the template engine.
Project-wide reference ids
Urubu has the concept of project-wide reference ids. You can use them to refer to link objects in your content and configuration. Their definition comes from two sources:
- global reference ids are mapped to link objects in the
_site.ymlconfiguration file, as discussed earlier.
- all content pages and folders objects have reference ids.
Project-wide references ids live in a single namespace. For pages and folders,
the id is a root-relative pathname starting with a slash
/ and without file
extension. By convention, global reference ids should not start with a
In your content and configuration info, you can also use relative reference ids. Urubu will resolve them depending on the file location in the project. In case of a name clash with a global reference id, you will have to disambiguate by adding pathname components.
In accordance with Markdown conventions, reference ids are case-insensitive.
Content files are Markdown files with extension
.md. They should start with
YAML front matter that defines a number of attributes, as in the following example:
--- title: Read me first layout: page date: 2014-01-15 --- <Markdown content>
The following attributes are predefined:
||Specifies the page title. Mandatory.|
||Specifies the layout, without the
||Specifies the date in YYYY-MM-DD format. Optional.|
||A tag or list of tags for the content.|
||Allows overriding of the output filename.|
layout attribute is mandatory, but can be given a
This is useful when the page content is used by other pages, but
no html output is required for the page itself.
In addition, you can add arbitrary user-defined attributes. All attributes are made available as page object attributes to the template engine.
Markdown in attributes
Optionally, you can use markdown format in front matter attributes. Markdown
processing is enabled by adding a
.md suffix to the attribute. The resulting
html code will be stored in a synthesized attribute without the
--- title: layout: page summary.md: | A summary of the page items as a list: * item 1 * item 2 * item 3 ---
After processing, the page object will have a
summary attribute with the html
Index files with basename
index.md are a special kind of content files. They
are used to specify the attributes and the content of a directory. There are
two options to specify the content, explicitly with the
content attribute or
implicitly using the
||Defines the content explicitly as a list of reference ids or local link objects.|
||Defines the attribute by which the content in the directory should be ordered.|
||Optional boolean attribute defines reverse order or not. Default is
order are mutually exclusive; you should use one of the two options.
A local link object is a mapping with either a
url key to an url, or a
key to a reference id as mandatory items. In addtion, you can specify a title
The ordering attribute can be predefined or user-defined, but it should be specified in each content file in the directory. As an example, you can specify that the content of a directory should be ordered as blog by the following front matter in the index file:
--- title: Blog layout: blog_index order: date reverse: true ---
The optional top-level directory called
tag has a predefined meaning. Urubu
uses the corresponding folder in the build to hold the tag-related content view
that it generates automatically. You can use the index file to set attributes
such as the
layout. However, the content will be generated by Urubu
automatically and needs not be set.