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:

index.<format>.twig
_default/list.<format>.twig
_default/page.<format>.twig

section:

section/<section>.<format>.twig
_default/section.<format>.twig
_default/list.<format>.twig

vocabulary:

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

term:

taxonomy/<term>.<format>.twig
_default/term.<format>.twig
_default/list.<format>.twig

page:

<section>/<layout>.<format>.twig
<layout>.<format>.twig
<section>/page.<format>.twig
page.<format>.twig
_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 .

{{ 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

Templates

Organization

Lookup rules

Variables

page

page.prev / page.next

page.pagination

Taxonomy

Vocabulary

Term

site

Additional variables

site.menus

site.language

site.language (beta)

cecil

Example

Functions

url(Page|string)

Options

minify(file_path)

readtime(string)

toCSS(file_path)

hash(file_path|URL)

getenv(var)