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

If page type is homepage:

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

If page type is section:

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

If page type is vocabulary:

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

If page type is term:

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

Otherwise (type is 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

config

Contains all variables under site key in configuration:

Example: {{ config.title }} is equivalent to {{ site.title }}.

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

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 Paginate total pages.
page.pagination.pages Paginate pages collection.
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

Variable Description
site.pages All pages (Collection).
site.pages.all All non-virtual pages (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).

cecil

Variable Description
cecil.url URL to the official website.
cecil.version 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 }}

Suggest a modification

Content Configuration