Jekyll style guide

The format

Config files should be written YAML.


Prefer multi-line arrays for readability and version control purposes.


  - one
  - two
  - three


numbers: [one, two, three]


Use the following site-wide variables, where appropriate:


The site’s base URL is only to be used when the resulting site lives at a subpath of the domain. Otherwise, the subpath should be nil, not /.

The site.github namespace

When your site is intended to be hosted on GitHub Pages, prefer values in the site.github namespace to manually specified values. In additional to reducing configuration noise, this will save headache if your repository is renamed, you add a CNAME, the project is forked, or if you preview the site locally.

Any value in the site.github namespace can be overridden as follows:

    branch: foo


While urlis not a mandatory config key, it is automatically set in development mode to http://localhost:4000 since Jekyll 3.3 and by GitHub Pages in production.

Prefer the absolute_url and relative_url filters in templates to calling site.github or site.baseurl directly to better account for environment and configuration inconsistencies.

<a href="{{ post.url | absolute_url }}">Post</a>

<a href="{{ "foo" | relative_url }}">Foo</a>