Introduction

Welcome to Urubu! My name is Jan Decaluwe and I am Urubu's author.

Urubu is a micro CMS for static websites. The qualification "micro* means that it has a small feature set, defined by what I need for my purposes. To know whether it is the right tool for you, check out Overview.

Urubu's design philosophy is radical reuse of great software and ideas from others. In the following sections, I will describe its concepts and how they are implemented.

Authoring

In Urubu, content is entered in Markdown format. This is a lightweight format that feels like a natural way to write content in plain text.

Markdown support in Urubu is implemented by the Python-Markdown package, that converts the format to html. Urubu also supports the industry standard Markdown Extra extensions, with useful features such as tables and definition lists.

Urubu supports nicely rendered code blocks, an essential feature for software projects documentation. Fenced Code Blocks are provided by the Markdown Extra extensions. This lets you enter language-specific code blocks without the need for indentation. The CodeHilite extension of Python-Markdown enables language-specific syntax highlighting via the Pygments library.

Configuration

The configuration options in Urubu are kept minimal, in the spirit of "There should be one obvious way to do it". Where used, the configuration format is YAML, implemented by the PyYAML library.

Configuration is mostly distributed, in the sense that every content file should have a front matter, that specifies the title, layout, date and so on. This idea is found in many tools, but Urubu reuses the technique from Jekyll. YAML front matter is specified between two sets of triple dashes.

Urubu extends this configuration technique by treating index files specially. Each folder in the site should have an index file (called index.md) that specifies the ordered folder content. This can be done explicitly by listing the files, or implicitly by specifying how the files should be ordered.

Templating

With templates you specify the html layout for a particular type of a page. In a template you can mix plain html with control structures and variable interpolation. The actual html page is generated by evaluating the template with the appropriate evaluation context provided by Urubu.

Urubu uses the Jinja2 templating language library.

Theming

A theme refers to the general look and feel of a web site. Partially this is defined by the templates as discussed above. The other part is defined in style sheets, with a technique known as Cascading Style Sheets (CSS). Basically this is a sophisticated technique to define how the various html elements should be rendered by the web browser.

With Urubu, you are free to design and use your own style sheets. However, it has been developed with Bootstrap in mind. Bootstrap is a professionally-designed framework with lots of useful predefined styles components. Urubu generates html that is Bootstrap-friendly, and infers the appropriate template variables for certain Bootstrap components.

A great feature of Bootstrap is that it is "mobile first". This means that your website will automatically adapt to any platform - smartphone, tablet or widescreen.

A notable project is Bootswatch. This is a set of themes designed as drop-in replacement for the stock bootstrap styles. This gives you an effortless option to change the look and feel of your website.

I am a big fan of Steve Krug's book Don't make me think, and I feel that the lessons from this book are still often ignored. Actually, the lack of focus of other tools on these ideas are the main reason why I wrote Urubu.

A main concept is good navigation. Urubu supports various techniques by inferring navigation-oriented variables and making them available to the template engine. Moreover, they work well with some well-defined and nicely style Bootstrap navigation components. In this way, you can easily implement the following:

  • a navbar for navigation between major sections
  • table of contents of a page in a sidebar
  • breadcrumbs
  • previous and next pager buttons
  • active page or section highlighting

Other techniques, independent from Urubu, can also help. Note for example that the sidebar on this page is "affixed": it moves as you scroll through the page, but never leaves the viewport. (Note: this description assumes that the viewport is wide enough to accomodate the sidebar.) At any time, the full structure of the page remains visible and available for navigation. This was implemented by borrowing code from the Bootstrap theme.

Project-wide reference ids

Markdown defines the concept of a reference link. This is a way to refer to a page or an url using a reference id. The syntax of a reference link is a reference id between square brackets, for example [intro].

Urubu supports the concept of project-wide reference ids. First, global reference ids can be defined in the site configuration file. Moreover, all content pages and folders have a corresponding reference id: their pathname without extension. In this case, reference links are similar to wiki links, the typical way to link between pages in wiki's.

Standard Markdown only resolves reference ids that are defined within the file. Urubu extends this behavior by resolving them over the project. This feature is implemented as a Markdown extension. Note that it doesn't require new syntax.

Project-wide reference ids are a unique Urubu feature.

One of the messages of Steve Krug's book is that the text that you click should be the title of the page where you land. Therefore, when you use reference links, Urubu will insert the page title in the generated html (unless you specify an alternative text explicitly).

Development and deployment

You can develop a Urubu project is like a software project, from a git or mercurial repository. This gives you best-in-class revision control. Moreover, all the workflows that these systems provide are available. For example, you can develop your website collaboratively on GitHub or Bitbucket. Finally, it is easy to automate deployment, triggered by a push of the generated site to an upstream repository.