Table of contents

Templates

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

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.

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

homepage:

  1. index.<format>.twig
  2. _default/list.<format>.twig
  3. _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

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).

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.time Site generation timestamp.

site.menus

KEY is the identifier of the menu collection (ie: main).

Variable Description
site.menus.KEY.name Menu entry name.
site.menus.KEY.url Menu entry URL (relative or absolute).
site.menus.KEY.weight Menu entry weight (useful to sort menu entries).

site.language

Variable Description
site.language Language code (ie: en).

site.language (beta)

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.

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.

Example

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

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: ouput format (ie: json)
{{ url(page, {canonical: true}) }}

minify(file_path)

Minify a CSS or a Javascript file.

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

readtime(string)

Return read time, in minutes.

{{ readtime(page.content) }} min

toCSS(file_path)

Compile a SCSS file (Sass) to CSS.

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

hash(file_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') }}

Filters

filterBy(variable, value)

Filter a pages collection by variable name/value.

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

sortByDate

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

{{ pages|sortByDate }}

sortByTitle

Sort a pages collection by title (natural).

{{ pages|sortByTitle }}

sortByWeight

Sort a menu entries collection by weight (lighter first).

{{ menu|sortByWeight }}

urlize

Converts a string to a slug.

{{ string|urlize }}

minifyCSS

Minify CSS.

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

minifyJS

Minify Javascript.

{% filter 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>
{% endfilter %}

SCSStoCSS

Compile Sass to CSS.

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

excerpt

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

{{ string|excerpt }}

excerptHtml

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

{{ string|excerptHtml }}

Built-in templates

Cecil comes with a set of built-in templates.

Internationalization (beta)

Cecil support text translation and date localization through Twig Extensions:

Translation

{% trans "Publication date:" %}

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

This extension use Gettext, so translation files (.mo) must be stored in the right directory of your project, like that:

<mywebsite>
└─ locale
   ├─ en_EN
   |  └─ LC_MESSAGES
   |     ├─ messages.mo
   |     └─ messages.po
   └─ fr_FR
      └─ LC_MESSAGES
         ├─ messages.mo
         └─ messages.po

Localization

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

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

Suggest a modification

Content Configuration