Templates

Cecil use Twig as template engine, so refer to the official documentation for basic usage.

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 files 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 best layout to use, for a given page, in a defined order.

In most of cases you don’t need to specify the template in layout variable: Cecil selects the most appropriate template for you.

Vocabulary:

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

homepage

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

section

<section>/list.<format>.twig
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

Variables

You can use variables from different scopes (site, page, etc.) in templates.

site

Contains all variables from the configuration file (config.yml).

Example:

title: "My amazing website !" is printed in a template with {{ site.title }}.

Built-in variables

Variable	Description
`site.pages`	Collection of (published) pages.
`site.pages.all`	Collection of (non-virtual) pages.
`site.taxonomies`	Collection of vocabularies.
`site.language`	Language code (default: `en`).
`site.time`	Timestamp of the last generation.

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

The static files collection can be accessed via site.static (if static load is enabled).

Each file has 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.data

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

Examples:

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

site.language

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 the current 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 root 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`	`homepage`, `page`, `section`, `vocabulary` or `term`	`page`
`page.filepath`	File system path.	`Blog/Post 1.md`

page.<prev/next>

Navigation between pages of 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

Pagination for homepage, section pages, and taxonomies.

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

Functions can be called to generate content. Functions are called by their name followed by parentheses (()) and may have arguments.

url

Turns a Page, a Page ID or a relative path into an URL.

{{ url(Page|page-id|path,{options}) }}

Option	Description	Type	Default
canonical	Prefixes URL with `baseurl`.	boolean	`false`
format	Page output format (ie: `json`).	string	`html`

Note: Prefer the url filter for assets.

Examples:

{{ url(page) }}
{{ url('page-id') }}
{{ url(menu.url) }}
{{ url('tags/'~tag) }}

asset

Creates an asset (CSS, JavaScript, image, audio, etc.) from a file path, an URL or an array of files path (bundle).

{{ asset(path|url|[paths],{options}) }}

Option	Description	Type	Default
fingerprint	Add the file content finger print to the file name.	boolean	`true`
minify	Compress file content (CSS and JavaScript).	boolean	`true`
filename	File to save content.	string
ignore_missing	Ignore if file don't exists.	boolean	`false`

See assets configuration to define the global behavior.

Uses filters to manipulate assets:

{{ asset('styles.scss')|html }}
{{ asset('styles.scss')|inline }}

Examples:

{{ asset('styles.css')|minify }}
{{ asset('scripts.js',{minify:false}) }}
{{ asset('image.png',{fingerprint:false}) }}
{{ asset(['poole.css','hyde.css'],{filename:styles.css}) }}
{{ asset('https://cdnjs.cloudflare.com/ajax/libs/anchor-js/4.3.1/anchor.min.js') }}

Attributes

file: filesystem path
path: relative path
ext: extension
type: media type (ie: image)
subtype: media sub type (ie: image/jpeg)
size: size in octets
source: content before compiling and/or minifying
content: file content
integrity: integrity hash
width: image width
height: image height
audio: Mp3Info

Examples:

{{ asset('image.png').width }}px
{{ asset('title.mp3').audio.duration|round }} min
{% set integrity = asset('styles.scss').integrity %}

integrity

Returns the hash (sha384) of a file.

{{ integrity(Asset|path) }}

Used for SRI (Subresource Integrity).

Example:

{{ integrity('styles.css') }}

readtime

Returns read time, in minutes.

{{ readtime(string) }}

Example:

{{ readtime(page.content) }} min

getenv

Gets the value of an environment variable.

{{ getenv(key) }}

Example:

{{ getenv('VAR') }}

Sorts

Sorting collections.

sort_by_title

Sorts a pages collection by title (with natural sort).

{{ <collection>|sort_by_title }}

sort_by_date

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

{{ <collection>|sort_by_date }}

sort_by_weight

Sorts a pages or menu collection by weight (lighter first).

{{ <collection>|sort_by_weight }}

sort

For more complex cases, you should use Twig’s native sort.

Example:

{% set files = site.static|sort((a, b) => a.date|date('U') < b.date|date('U')) %}

Filters

Filtering collections.

filter_by

Filters a pages collection by variable name/value.

{{ <collection>|filter_by(variable, value) }}

Example:

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

filter

For more complex cases, you should use Twig’s native filter.

Example:

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

url

Turns a Page, an Asset or a path into an URL.

{{ <Page|Asset|path>|url({options}) }}

Option	Description	Type	Default
canonical	Prefixes with `baseurl`.	boolean	`false`
format	Defines Page output format (ie: `json`).	string	`html`

Examples:

{{ page|url }}
{{ asset('styles.css')|url({canonical:true}) }}

markdown_to_html

Converts a Markdown string to HTML.

{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
{# Markdown here #}
{% endapply %}

Examples:

{% set markdown = '**This is bold text**' %}
{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
**This is bold text**
{% endapply %}

json_decode

Converts a JSON string to an array.

{{ json|json_decode }}

Example:

{% set json = '{"foo":"bar"}' %}
{% set array = json|json_decode %}
{{ array.foo }}

slugify

Converts a string to a slug.

{{ string|slugify }}

excerpt

Truncates a string and appends suffix.

{{ string|excerpt(integer,suffix) }}

Option	Description	Type	Default
length	Truncates after this number of characters.	integer	450
suffix	Appends characters.	string	`…`

Examples:

{{ variable|excerpt }}
{{ variable|excerpt(250,'...') }}

excerpt_html

Reads characters before  or .

{{ string|excerpt_html }}

preg_split

Split a string into an array using a regular expression.

{{ string|preg_split(pattern, limit) }}

Example:

{% set headers = page.content|preg_split('/<h3[^>]*>/') %}

preg_match_all

Perform a regular expression match and return the group for all matches.

{{ string|preg_match_all(pattern, group) }}

Example:

{% set tags = page.content|preg_match_all('/<[^>]+>(.*)<\\/[^>]+>/') %}

to_css

Compiles a Sass file (to CSS).

{{ asset(path)|to_css }}
{{ path|to_css }}

Examples:

{{ asset('styles.scss')|to_css }}
{{ 'styles.scss'|to_css }} {# deprecated #}

fingerprint

Add the file content finger print to the file name.

{{ asset(path)|fingerprint }}
{{ path|fingerprint }}

Examples:

{{ asset('styles.css')|fingerprint }}
{{ 'styles.css'|fingerprint }} {# deprecated #}

minify

Minifying a CSS or a JavaScript file.

{{ asset(path)|minify }}
{{ path|minify }} {# deprecated #}

Examples:

{{ asset('styles.css')|minify }}
{{ 'styles.css'|minify }} {# deprecated #}
{{ asset('scripts.js')|minify }}

inline

Outputs the content of an Asset.

{{ asset(path)|inline }}

Example:

{{ asset('styles.css')|inline }}

html

Turns an asset into an HTML element.

{{ asset(path)|html({attributes, options}) }}

Option	Description	Type	Default
attributes	Adds `name="value"` couple to the HTML element.	array
options	Rendering format. Preload: `{preload:true}`.	array

Available for CSS, JavaScript and image file.

Examples:

{{ asset('image.png')|html({title:'Title',alt:'Alternative'}) }}

{{ asset('styles.css')|html({},{preload:true}) }}

minify_css

Minifying CSS.

{{ variable|minify_css }}

{% apply minify_css %}
{# CSS here #}
{% endapply %}

Examples:

{% set styles = 'some CSS here' %}
{{ styles|minify_css }}

<style>
{% apply minify_css %}
  html {
    background-color: #fcfcfc;
    color: #444;
  }
{% endapply %}
</style>

minify_js

Minifying JavaScript.

{{ variable|minify_js }}

{% apply minify_js %}
{# JavaScript here #}
{% endapply %}

Examples:

{% set script = 'some JavaScript here' %}
{{ script|minify_js }}

<script>
{% apply minify_js %}
  var test = 'test';
  console.log(test);
{% endapply %}
</script>

scss_to_css

Compiles a Sass (to CSS).

{{ variable|scss_to_css }}

{% apply scss_to_css %}
{# SCSS here #}
{% endapply %}

Alias: sass_to_css.

Examples:

{% set scss = 'some SCSS here' %}
{{ scss|scss_to_css }}

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

resize

Resizes an image to a specified with.

Experimental

{{ <image_path>|resize(integer) }}

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

Example:

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

Built-in templates

Cecil comes with a set of built-in templates.

Default templates

_default/page.html.twig: A very simple default main template with a clean CSS.
_default/list.html.twig: A pages list with pagination.
_default/vocabulary.html.twig: A basic list of all terms of a vocabulary.
_default/list.atom.twig: A clean Atom feed for sections.
_default/list.rss.twig: A clean RSS feed for sections.

Utility templates

robots.txt.twig: The robots.txt template: allow all pages except 404, with a reference to the XML sitemap.
sitemap.xml.twig: The sitemap.xml template: list all pages sorted by date.

Component templates

partials/pagination.html.twig: A simple pagination component for list templates with "Older" and "Newer" links.
partials/metatags.html.twig: All metatags in one component: title, description, canonical, open-graph, twitter card, etc. See configuration.
partials/googleanalytics.js.twig: Google Analytics traking script. See configuration.

Internationalization

Cecil support text translation and date localization through Twig Extensions.

Experimental

Translation

{% trans "Publication date:" %}

{% trans variable %}

{% trans %}
    Hey {{ name }}, I have one apple.
{% plural apple_count %}
    Hey {{ name }}, I have {{ count }} apples.
{% endtrans %}

{{ variable|default(default_value|trans) }}

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

See the i18n Extension documentation.

Requirements: Gettext PHP extension.

Localization

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

See the Intl Extension documentation.

Requirements: Intl PHP extension.

Suggest a modification

← Content Configuration →