What's on this page

Example
Files organization
Lookup rules
Variables
Functions
Sorts
Filters
Localization
Built-in templates
Extend
Theme

Templates

Cecil is powered by the Twig template engine, so please refer to the official documentation to learn how to use it.

Example

{# this is a template example #}
<h1>{{ page.title }} - {{ site.title }}</h1>
<span>{{ page.date|date('j M Y') }}</span>
<p>{{ page.content }}</p>
<ul>
{% for tag in page.tags %}
  <li>{{ tag }}</li>
{% endfor %}
</ul>

{# #}: adds comments
{{ }}: outputs content of variables or expressions
{% %}: executes statements, like loop (for), condition (if), etc.
|filter(): filters or formats content

Files organization

There is two kinds of templates, layouts and others templates: layouts are used to render pages, and each of them can include templates.

Templates files are stored in the layouts/ directory and must be named according to the following convention:

layouts/(<section>/)<type>|<layout>.<format>(.<language>).twig

<section> (optional): The section of the page (e.g.: blog).
<type>: The page type: home (or index) for homepage, list for list, page for page, etc. (See Lookup rules for details).
<layout> (optional): The custom layout name defined in the front matter of the page (e.g.: layout: my-layout).
<language> (optional): The language of the page (e.g.: fr).
<format>: The output format of the rendered page (e.g.: html, rss, json, xml, etc.).
".twig": The mandatory Twig file extension.

Examples:

layouts/home.html.twig       # `type` is "homepage"
layouts/page.html.twig       # `type` is "page"
layouts/page.html.fr.twig    # `type` is "page" and `language` is "fr"
layouts/my-layout.html.twig  # `layout` is "my-layout"
layouts/blog/list.html.twig  # `section` is "blog"
layouts/blog/list.rss.twig   # `section` is "blog" and `format` is "rss"

<mywebsite>
├─ ...
├─ layouts                  <- Layouts and templates
|  ├─ my-layout.html.twig
|  ├─ index.html.twig       <- Used by type "homepage"
|  ├─ list.html.twig        <- Used by types "homepage", "section" and "term"
|  ├─ list.rss.twig         <- Used by types "homepage", "section" and "term", for RSS output format
|  ├─ page.html.twig        <- Used by type "page"
|  ├─ ...
|  ├─ _default              <- Default layouts, that can be easily extended
|  |  ├─ list.html.twig
|  |  ├─ page.html.twig
|  |  └─ ...
|  └─ partials
|     ├─ footer.html.twig   <- Included template
|     └─ ...
└─ themes
   └─ <theme>
      └─ layouts            <- Theme layouts and templates
         └─ ...

Lookup rules

In most of cases you don’t need to specify the layout: Cecil selects the most appropriate layout, according to the page type.

For example, the HTML output of home page (index.md) will be rendered:

with my-layout.html.twig if the layout variable is set to "my-layout" (in the front matter)
if not, with home.html.twig if the file exists
if not, with index.html.twig if the file exists
if not, with list.html.twig if the file exists
etc.

All rules are detailed below, for each page type, in the priority order.

Type homepage

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

Type page

<section>/<layout>.<format>.twig
<layout>.<format>.twig
<section>/page.<format>.twig
page.<format>.twig
_default/<layout>.<format>.twig
_default/page.<format>.twig

Type section

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

Type vocabulary

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

Type term

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

Variables

The application passes variables to the templates for manipulation in the template. Variables may have attributes or elements you can access, too.
Use a dot (.) to access attributes of a variable: {{ foo.bar }}

You can use variables from different scopes: site, page, cecil.

site

The site variable contains all variables from the configuration and built-in variables.

Example:

title: "My amazing website!"

Can be displayed in a template with:

{{ site.title }}

Built-in variables

Variable	Description
`site.home`	ID of the home page.
`site.pages`	Collection of pages, in the current language.
`site.pages.showable`	Same as `site.pages` but filtered by "showable" status (published pages and not virtual/redirect/excluded).
`site.page('id')`	A page with the given ID.
`site.allpages`	Collection of all pages, regardless of their language.
`site.taxonomies`	Collection of vocabularies.
`site.time`	Timestamp of the last generation.
`site.debug`	Debug mode: `true` or `false`.

In some case you can encounter conflicts between configuration and built-in variables (e.g.: pages.default configuration), so you can use config.<variable> (with <variable> is the name/path of the variable) to access directly to the raw configuration). Example:

{{ config.pages.default.sitemap.priority }}

site.menus

Loop on site.menus.<menu> to get each entry of the <menu> collection (e.g.: main).

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

Example:

<nav>
  <ol>
  {% for entry in site.menus.main|sort_by_weight %}
    <li><a href="{{ url(entry.url) }}" data-weight="{{ entry.weight }}">{{ entry.name }}</a></li>
  {% endfor %}
  </ol>
</nav>

site.language

Informations about the current language.

Variable	Description
`site.language`	Language code (e.g.: `en`).
`site.language.name`	Language name (e.g.: `English`).
`site.language.locale`	Language locale code (e.g.: `en_EN`).
`site.language.weight`	Language position in the `languages` list.

site.static

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

Each file exposes the following properties:

path: relative path (e.g.: /images/img-1.jpg)
date: creation date (timestamp)
updated: modification date (timestamp)
name: name (e.g.: img-1.jpg)
basename: name without extension (e.g.: img-1)
ext: extension (e.g.: jpg)
exif: image EXIF data (array)
audio: Mp3Info object

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

page

Contains built-in 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 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`	Collection of all sub pages.	Collection
`page.pages.showable`	`page.pages` with "showable" pages only.	Collection
`page.type`	`homepage`, `page`, `section`, `vocabulary` or `term`.	`page`
`page.filepath`	File system path.	`Blog/Post 1.md`
`page.translations`	Collection of translated pages.	Collection

page.<prev/next>

Navigation between pages in a same Section.

Variable	Description	Example
`page.prev`	Previous page.	Page
`page.next`	Next page.	Page

Example:

<a href="{{ url(page.prev) }}">{{ page.prev.title }}</a>

page.paginator

Paginator help you to build a navigation for list's pages: homepage, sections, and taxonomies.

Variable	Description
`page.paginator.pages`	Pages Collection.
`page.paginator.pages_total`	Number total of pages.
`page.paginator.count`	Number of paginator's pages.
`page.paginator.current`	Position index of the current page.
`page.paginator.links.first`	Page ID of the first page.
`page.paginator.links.prev`	Page ID of the previous page.
`page.paginator.links.self`	Page ID of the current page.
`page.paginator.links.next`	Page ID of the next page.
`page.paginator.links.last`	Page ID of the last page.
`page.paginator.links.path`	Page ID without the position index.

Example:

{% if page.paginator %}
<div>
  {% if page.paginator.links.prev is defined %}
  <a href="{{ url(page.paginator.links.prev) }}">Previous</a>
  {% endif %}
  {% if page.paginator.links.next is defined %}
  <a href="{{ url(page.paginator.links.next) }}">Next</a>
  {% endif %}
</div>
{% endif %}

Example:

{% if page.paginator %}
<div>
  {% for paginator_index in 1..page.paginator.count %}
    {% if paginator_index != page.paginator.current %}
      {% if paginator_index == 1 %}
  <a href="{{ url(page.paginator.links.first) }}">{{ paginator_index }}</a>
      {% else %}
  <a href="{{ url(page.paginator.links.path ~ '/' ~ paginator_index) }}">{{ paginator_index }}</a>
      {% endif %}
    {% else %}
  {{ paginator_index }}
    {% endif %}
  {% endfor %}
</div>
{% endif %}

Taxonomy

Variables available in vocabulary and term templates.

Vocabulary

Variable	Description
`page.plural`	Vocabulary name in plural form.
`page.singular`	Vocabulary name in 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 of 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

Creates a valid URL for a page, an asset, a page ID or a path.

{{ url(value, {options}) }}

Option	Description	Type	Default
canonical	Prefixes path with `baseurl` or use `canonical.url`.	boolean	`false`
format	Defines page output format (e.g.: `json`).	string	`html`
language	Trying to force page language (e.g.: `fr`).	string	null

Examples:

# page
{{ url(page) }}
{{ url(page, {canonical: true}) }}
{{ url(page, {format: json}) }}
{{ url(page, {language: fr}) }}
# asset
{{ url(asset('styles.css')) }}
# page ID
{{ url('page-id') }}
# path
{{ url(menu.url) }}
{{ url('tags/' ~ tag) }}

For convenience the url function is also available as a filter:

# page
{{ page|url }}
{{ page|url({canonical: true, format: json, language: fr}) }}
# asset
{{ asset('styles.css')|url }}

asset

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

{{ asset(path, {options}) }}

Option	Description	Type	Default
fingerprint	Add the file content finger print to the file name.	boolean	`true`
minify	Compress file content (CSS or JavaScript).	boolean	`true`
filename	File where to save content.	string	`styles.css` or `scripts.js`
ignore_missing	Do not stop build if file don't exists.	boolean	`false`
remote_fallback	Load a local asset if the remote one don't exists.	string	`null`

Examples:

# CSS
{{ asset('styles.css') }}
# CSS bundle
{{ asset(['poole.css', 'hyde.css'], {filename: styles.css}) }}
# JavaScript
{{ asset('scripts.js') }}
# image
{{ asset('image.jpeg') }}
# remote file
{{ asset('https://cdnjs.cloudflare.com/ajax/libs/anchor-js/4.3.1/anchor.min.js', {minify: false}) }}
# with filter
{{ asset('styles.css')|minify }}
{{ asset('styles.scss')|to_css|minify }}

Asset attributes

Assets created with the asset() function expose some useful attributes:

file: filesystem path
files: array of filesystem path in case of bundle
filename: file name
path_source: relative path before processing
path: relative path
missing: true if file not found, but missing is ollowed
ext: extension
type: media type (e.g.: image)
subtype: media sub type (e.g.: image/jpeg)
size: size in octets
content_source: content before processing
content: file content
integrity: integrity hash
width: image width
height: image height
exif: image EXIF data as array
audio: Mp3Info object
video: array of video dimensions (width and height)

Examples:

# image width in pixels
{{ asset('image.png').width }}px
# photo's date in seconds
{{ asset('photo.jpeg').exif.DateTimeOriginal|date('U') }}
# MP3 song duration in minutes
{{ asset('title.mp3').audio.duration|round }} min
# file integrity hash
{% set integrity = asset('styles.scss').integrity %}

image_srcset

Builds the HTML img srcset (responsive) attribute of an image Asset.

{{ image_srcset(asset) }}

Examples:

{% set asset = asset(image_path) %}
<img src="{{ url(asset) }}" width="{{ asset.width }}" height="{{ asset.height }}" alt="" class="asset" srcset="{{ image_srcset(asset) }}" sizes="{{ image_sizes('asset') }}">

image_sizes

Returns the HTML img sizes attribute based on a CSS class name.
It should be use in conjunction with the image_srcset function.

{{ image_sizes('class') }}

Examples:

{% set asset = asset(image_path) %}
<img src="{{ url(asset) }}" width="{{ asset.width }}" height="{{ asset.height }}" alt="" class="asset" srcset="{{ image_srcset(asset) }}" sizes="{{ image_sizes('asset') }}">

integrity

Creates the hash (sha384) of a file (from an asset or a path).

{{ integrity(asset) }}

Used for SRI (Subresource Integrity).

Example:

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

readtime

Determines read time of a text, in minutes.

{{ readtime(text) }}

Example:

{{ readtime(page.content) }} min

getenv

Gets the value of an environment variable from its key.

{{ getenv(var) }}

Example:

{{ getenv('VAR') }}

dump

The dump function dumps information about a template variable. This is mostly useful to debug a template that does not behave as expected by introspecting its variables:

{{ dump(user) }}

d

The d() function is the HTML version of dump() and use the Symfony VarDumper Component behind the scenes.

{{ d(variable, {theme: light}) }}

If variable is not provided then the function returns the current Twig context
Available themes are « light » (default) and « dark »

Sorts

Sorting collections (of pages, menus or taxonomies).

sort_by_title

Sorts a collection by title (with natural sort).

{{ <collection>|sort_by_title }}

Example:

{{ site.pages|sort_by_title }}

sort_by_date

Sorts a collection by date (most recent first).

{{ <collection>|sort_by_date(variable='date', desc_title=false) }}

Example:

# sort by date
{{ site.pages|sort_by_date }}
# sort by updated variable instead of date
{{ site.pages|sort_by_date(variable='updated') }}
# sort items with the same date by desc title
{{ site.pages|sort_by_date(desc_title=true) }}
# reverse sort
{{ site.pages|sort_by_date|reverse }}

sort_by_weight

Sorts a collection by weight (lighter first).

{{ <collection>|sort_by_weight }}

Example:

{{ site.menus.main|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

Variables can be modified by filters. Filters are separated from the variable by a pipe symbol (|). Multiple filters can be chained. The output of one filter is applied to the next.

{{ page.title|truncate(25)|capitalize }}

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']) %}

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

yaml_parse

Converts a YAML string to an array.

{{ yaml|yaml_parse }}

Example:

{% set yaml = 'key: value' %}
{% set array = yaml|yaml_parse %}
{{ array.key }}

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 after  or  tag.
See Content documentation for details.

{{ string|excerpt_html({separator, capture}) }}

Option	Description	Type	Default
separator	String to use as separator.	string	`excerpt\|break`
capture	Part to capture, `before` or `after` the separator.	string	`before`

Examples:

{{ variable|excerpt_html }}
{{ variable|excerpt_html({separator: 'excerpt|break', capture: 'before'}) }}
{{ variable|excerpt_html({capture: 'after'}) }}

to_css

Compiles a Sass file to CSS.

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

Examples:

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

fingerprint

Add the file content finger print to the file name.

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

Examples:

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

minify

Minifying a CSS or a JavaScript file.

{{ asset(path)|minify }}

Examples:

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

minify_css

Minifying a CSS string.

{{ 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 a JavaScript string.

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

{{ asset(image_path)|resize(integer) }}

Example:

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

webp

Converts an image to WebP format.

Example:

<picture>
    <source type="image/webp" srcset="{{ asset(image_path)|webp }}">
    <img src="{{ url(asset(image_path)) }}" width="{{ asset(image_path).width }}" height="{{ asset(image_path).height }}" alt="">
</picture>

dataurl

Returns the data URL of an asset.

{{ asset(path)|dataurl }}
{{ asset(image_path)|dataurl }}

lqip

Returns a Low Quality Image Placeholder (100x100 px, 50% blurred) as data URL.

{{ asset(image_path)|lqip }}

dominant_color

Returns the dominant hexadecimal color of an image.

{{ asset(image_path)|dominant_color }}
# #F2D07F

inline

Outputs the content of an Asset.

{{ asset(path)|inline }}

Example:

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

html

Converts 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	`{preload: true}`: preloads CSS. `{responsive: true}`: creates responsives images. `{webp: true}`: creates WebP versions of the image.	array

Examples:

{# image without specific attributes nor options #}
{{ asset('image.png')|html }}

{# image with specific attributes and options #}
{{ asset('image.jpg')|html({alt: 'Description', loading: 'lazy'}, {responsive: true, webp: true}) }}

{# with named argument `options` #}
{{ asset('image.jpg')|html(options={responsive: true}) }}

{{ asset('styles.css')|html({media: 'print'}) }}

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

{{ asset('script.js')|html }}

preg_split

Splits a string into an array using a regular expression.

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

Example:

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

preg_match_all

Performs 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('/<[^>]+>(.*)<\/[^>]+>/') %}

hex_to_rgb

Converts a hexadecimal color to RGB.

{{ color|hex_to_rgb }}

Localization

Cecil support text translation and date localization.

Text translation

Uses the trans tag or filter to translate texts in templates.

{% trans with variables into locale %}{% endtrans %}

{{ message|trans(variables = []) }}

Examples

{% trans %}Hello World!{% endtrans %}

{{ message|trans }}

Include variables:

{% trans with {'%name%': 'Arnaud'} %}Hello %name%!{% endtrans %}

{{ message|trans({'%name%': 'Arnaud'}) }}

Force locale:

{% trans into 'fr_FR' %}Hello World!{% endtrans %}

Pluralize:

{% trans with {'%count%': 42}%}{0}I don't have apples|{1}I have one apple|]1,Inf[I have %count% apples{% endtrans %}

Translation files

Translation files must be named messages.<locale>.<format> and stored in the translations directory.
Cecil supports yaml and mo (Gettext) file formats by default.

Example:

<mywebsite>
└─ translations
   ├─ messages.fr_FR.mo   <- Machine Object format
   └─ messages.fr_FR.yaml <- Yaml format

Date localization

Uses the Twig format_date filter to localize a date in templates.

{{ page.date|format_date('long') }}
# September 30, 2022

Supported values are: short, medium, long, and full.

Built-in templates

Cecil comes with a set of built-in templates.

If you need to modify built-in templates, you can easily extract them via the following command: they will be copied in the "layouts" directory of your site.

php cecil.phar util:extract

Default templates

_default/page.html.twig: A simple main template with a clean CSS.
_default/list.html.twig: A pages list with (an optional) pagination.
_default/list.atom.twig: An Atom feed.
_default/list.rss.twig: A RSS feed.
_default/vocabulary.html.twig: A simple list of all terms of a vocabulary.
_default/sitemap.xml.twig: The sitemap.xml template: list all pages sorted by date.
_default/robots.txt.twig: The robots.txt template: allow all pages except 404, with a reference to the XML sitemap.
_default/404.html.twig: A basic error 404 ("Page not found") template.
_default/redirect.html.twig: The redirect template.

Partial templates

partials/navigation.html.twig: A main menu navigation.
partials/paginator.html.twig: A simple paginated navigation for list templates with "Previous" and "Next" links.
partials/metatags.html.twig: All metatags in one template: title, description, canonical, open-graph, twitter card, etc. See configuration.
partials/languages.html.twig: A basic switcher between languages.

Extend

Theme

It’s easy to build a Cecil theme: you just have to create a folder <theme> with the following structure:

<mywebsite>
└─ themes
   └─ <theme>
      ├─ config.yml
      ├─ assets
      ├─ layouts
      ├─ static
      └─ translations

Suggest a modification

← Content Configuration →

What's on this page

Example
Files organization
Lookup rules
Variables
Functions
Sorts
Filters
Localization
Built-in templates
Extend
Theme

Templates

Example

Files organization

Lookup rules

Type homepage

Type page

Type section

Type vocabulary

Type term

Variables

site

Built-in variables

site.menus

site.language

site.static

site.data

page

page.<prev/next>

page.paginator

Taxonomy

Vocabulary

Term

cecil

Functions

url

asset

Asset attributes

image_srcset

image_sizes

integrity

readtime

getenv

dump

d

Sorts

sort_by_title

sort_by_date

sort_by_weight

sort

Filters

filter_by

filter

markdown_to_html

toc

json_decode

yaml_parse

slugify

excerpt

excerpt_html

to_css

fingerprint

minify

minify_css

minify_js

scss_to_css

resize

webp

dataurl

lqip

dominant_color

inline

html

preg_split

preg_match_all

hex_to_rgb

Localization

Text translation

Examples

Translation files

Date localization

Built-in templates

Default templates

Partial templates

Extend

Theme