Templates

Cecil use Twig as template engine, so refer to the official documentation to know how to use it.

Example

<h1>{{ page.title }} | {{ site.title }}</h1>
<span>{{ page.date|date('j M Y') }}</span>
<p>{{ page.content }}</p>
<p>{{ page.customvar }}</p>

Files organization

Templates are stored in layouts/.

<mywebsite>
├─ content
├─ layouts
|  ├─ _default           <- Contains default templates
|  |  ├─ list.html.twig  <- Used by "section" and "term" pages type
|  |  └─ page.html.twig  <- Used by "page" pages type
|  └─ index.html.twig    <- Used by the "homepage" type
└─ themes
   └─ <theme>            <- A custom theme
      ├─ layouts
      └─ ...

Lookup rules

Cecil searches for the layout to use, for a given page, in a defined order.

Notes:

<format> is the output format (ie: html).
<layout> is the value of variable layout set in front matter (ie: layout: post).
<section> is the page’s Section (ie: blog).

homepage

  1. <layout>.<format>.twig
  2. index.<format>.twig
  3. _default/list.<format>.twig
  4. _default/page.<format>.twig

section

  1. section/<section>.<format>.twig
  2. _default/section.<format>.twig
  3. _default/list.<format>.twig

vocabulary

  1. taxonomy/<plural>.<format>.twig
  2. _default/vocabulary.<format>.twig

term

  1. taxonomy/<term>.<format>.twig
  2. _default/term.<format>.twig
  3. _default/list.<format>.twig

page

  1. <section>/<layout>.<format>.twig
  2. <layout>.<format>.twig
  3. <section>/page.<format>.twig
  4. page.<format>.twig
  5. _default/page.<format>.twig

Variables

site

Contains all variables in configuration file (config.yml).

Example:

{{ site.title }}

Additional variables

Variable Description
site.pages All (published) pages (Collection).
site.pages.all All (non-virtual) pages (Collection).
site.taxonomies All vocabularies (Collection).
site.language Language code (default: en).
site.time Site generation timestamp.

site.menus

Loop on site.menus.<key> to get each entry of <key>.

<key> is the identifier of the menu collection (ie: main).

Variable Description
<entry>.name Menu entry name.
<entry>.url Menu entry URL (relative or absolute).
<entry>.weight Menu entry weight (useful to sort menu entries).

site.data

A data collection can be accessed via site.data.<filename> (without file extension).

Example:

  • data/authors.yml : site.data.authors
  • data/galleries/gallery-1.json : site.data.galleries.gallery-1

site.static

The static files collection can be accessed via site.static.

Each file have the following properties:

  • path: relative path (ie: /images/img-1.jpg)
  • date: creation date (timestamp)
  • updated: modification date (timestamp)
  • name: name (ie: img-1.jpg)
  • basename: name without extension (ie: img-1)
  • ext: extension (ie: jpg)

site.language

Experimental

Variable Description
site.language.name Language full name (ie: English).
site.language.locale Language locale code (ie: en_EN).
site.language.weight Language position in languages list.

page

Contains variables of a Page and those set in the front matter.

Variable Description Example
page.id Unique identifier. blog/post-1
page.title File name (without extension). Post 1
page.date File creation date. DateTime
page.updated File modification date. DateTime
page.body File body. Markdown
page.content File body converted in HTML. HTML
page.section File first folder (slugified). blog
page.path File path (slugified). blog/post-1
page.slug File name (slugified). post-1
page.tags Array of tags. [Tag 1, Tag 2]
page.categories Array of categories. [Category 1, Category 2]
page.pages Subpages. Collection
page.type page, homepage, section, vocabulary or term page
page.filepath File system path. Blog/Post 1.md

page.<prev/page>.next

Pages navigation in a section.

Variable Description
page.<prev/next>.id ID of the previous / next page (ie: blog/post-2).
page.<prev/next>.path Path of the previous / next page (ie: blog/post-2).
page.<prev/next>.title Title of the previous / next page (ie: Post 2).

page.pagination

Variable Description
page.pagination.totalpages Paginated total pages.
page.pagination.pages Paginated pages collection.
page.pagination.current Number of the current page.
page.pagination.count Number of the last page.
page.pagination.links.self ID of the current page.
page.pagination.links.first ID of the first page.
page.pagination.links.prev ID of the previous page.
page.pagination.links.next ID of the next page.
page.pagination.links.last ID of the last page.

Taxonomy

Variables available in vocabulary and term layouts.

Vocabulary
Variable Description
page.plural Vocabulary name (plural form).
page.singular Vocabulary name (singular form).
page.terms List of terms (Collection).
Term
Variable Description
page.term Term ID.
page.pages List of pages in this term (Collection).

cecil

Variable Description
cecil.url URL to the official website.
cecil.version Cecil current version.
cecil.poweredby Print Cecil v%s with %s is the current version.

Functions

url(Page|string)

Create an URL.

{{ url(page) }}
{{ url(menu.url) }}
{{ url('css/style.css') }}
{{ url('https://cecil.app') }}
{{ url('tags/' ~ tag) }}

Options:

  • canonical: true|false
  • addhash: true|false
  • format: output format (ie: json)
{{ url(page, {canonical: true}) }}

readtime(string)

Return read time, in minutes.

{{ readtime(page.content) }} min

toCSS(path)

Compile a Sass file to CSS.

{{ toCSS('style/style.scss') }}

minify(path)

Minify a CSS or a JavaScript file.

{{ minify('css/style.css') }}
{{ minify('js/script.js') }}

hash(path|URL)

Return the hash (sha384) of a file.

{{ hash('style/style.css') }}
{{ hash('https://example.com/framework.js') }}

Useful for SRI (Subresource Integrity).

getenv(var)

Gets the value of an environment variable.

{{ getenv('VAR') }}

Sorts

sortByTitle

Sort a collection (Pages) by title (with natural sort).

{{ pages|sortByTitle }}

sortByDate

Sort a collection (Pages) by date (most recent first).

{{ pages|sortByDate }}

sortByWeight

Sort a collection (Pages or Menu) by weight (lighter first).

{{ menu|sortByWeight }}

Filters

filterBy(variable, value)

Filter a pages collection by variable name and value.

{{ pages|filterBy('section', 'blog') }}

For more complex cases, you should use Twig's native filter:

{{ pages|filter(p => p.id not in ['id-1', 'id-2']) }}

urlize

Converts a string to a slug.

{{ string|urlize }}

excerpt

Truncate a string to 450 char and adds “…“.

{{ string|excerpt }}

excerptHtml

Read characters before <!-- excerpt -->.

{{ string|excerptHtml }}

SCSStoCSS

Compile Sass to CSS.

{% apply SCSStoCSS %}
<style>
  $color: #abc;
  div { color: lighten($color, 20%); }
</style>
{% endapply %}

minifyCSS

Minify CSS.

{% apply minifyCSS %}
<style>
  html {
    background-color: #fcfcfc;
    color: #444;
    font: 100%/3rem 'Raleway', sans-serif;
  }
</style>
{% endapply %}

minifyJS

Minify JavaScript.

{% apply minifyJS %}
<script>
  (function(d) {
    var wf = d.createElement('script'), s = d.scripts[0];
    wf.src = 'https://ajax.googleapis.com/ajax/libs/webfont/1.6.16/webfont.js';
    s.parentNode.insertBefore(wf, s);
 })(document);
</script>
{% endapply %}

resize(width)

Experimental

Resize in image.

Ratio is preserved, the original file is not altered and the resized version is stored in /images/thumbs/<resize>/path/to/image.ext.

{{ page.image|resize(300) }}

Built-in templates

Cecil comes with a set of built-in templates.

Internationalization

Experimental

Cecil support text translation and date localization through Twig Extensions.

Translation

{% trans "Publication date:" %}

See https://twig-extensions.readthedocs.io/en/latest/i18n.html.

Translation files (.mo) must be stored in the right directory of your project:

<mywebsite>
└─ locale
   └─ fr_FR              <- Language code
      └─ LC_MESSAGES
         ├─ messages.mo  <- Compiled translation file
         └─ messages.po  <- Translation file

This extension required Gettext.

Localization

{{ page.date|localizeddate('long', 'none') }}

See https://twig-extensions.readthedocs.io/en/latest/intl.html.

This extension required intl.

Suggest a modification

Content Configuration

Table of contents