Maintenance Basics

Understanding Building Blocks

As everything is based on Jekyll, maintainers are strongly adviced to read and understand the Jekyll documentation. Especially the chapters on structure and variables. This includes good knowledge of the Liquid templating language.

Layouts

Layouts define the general layout of the generated HTML pages and can be nested. It's probably best to explain with an example: _layouts/page.html and _layouts/default.html

Whenever a file (i.e. about/index.md) defines the page layout in its YAML front matter, _layouts/page.html is used.

Here, "used" means, that the content of the file (i.e. everything below the YAML front matter) is set to the page.html's content variable, thus inserted by Liquid wherever {{ content }} is used. Also all other Liquid tags are evaluated, e.g. additional partials included and other variables' values inserted.

In case the YAML front matter of the layout defines another layout (as in the case of page.html), the other layout is used and the fully extended content of the page layout is set to the content variable of the outer layout, i.e. default.

The default layout defined in default.html provides the root of a HTML document and has no YAML front matter defined, thus it is also the root layout for all pages and layouts specifying default as their layout in the YAML front matter.

Partials

Partials, in the wording of web designers, are small logical blocks of HTML templates usable throught a project. From a programmer's perspective, these can be seen as global, free floating methods/functions.

Here, they reside in _includes, are sometimes also called includes and are accessible via the Liquid tag include:

{% include path/to/partial.html %}

(this places the content of _includes/path/to/partial.html wherever this Liquid tag is used)

The full set of Liquid tags, filters and variables can be used, allowing for complex conditional rendering of a page's content. For a more complex example see _includes/post/date.html.

Important Building Blocks

Modifying Navigation Bar

The top navigation bar is constructed in _includes/header.html with the help of a few partials residing in _includes/navs.

The actual navigation links are constructed according to Twitter Bootstrap and conditionally styled with some Liquid Tags.