Files organization

Kinds of templates

There are three kinds of templates: layouts, components, and other templates. Layouts are used to render pages, and each layout can include templates and components.

Naming convention

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

<format>

The output format of the rendered page (e.g.: html, rss, json, xml, etc.).

<language> (optional)

The language of the page (e.g.: fr).

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"

<my-site>
├─ ...
├─ layouts
|  ├─ index.html.twig      # Used by type "homepage"
|  ├─ list.html.twig       # Used by types "homepage" and "section"
|  ├─ list.rss.twig        # Used by types "homepage" and "section", for RSS output format
|  ├─ page.html.twig       # Used by type "page"
|  ├─ taxonomy
|  |  ├─ tags.html.twig    # Used by type "vocabulary" of `tags` (list of terms)
|  |  └─ tag.html.twig     # Used by type "term" of `tags` (list of pages)
|  ├─ my-layout.html.twig  # Used by pages with `layout: my-layout` in the front matter
|  ├─ ...
|  └─ partials             # Included templates
|     ├─ footer.html.twig
|     └─ ...
└─ themes                  # Themes layouts and templates
   └─ ...

Built-in templates

Cecil comes with a set of built-in 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:

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

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

Type homepage

1. <layout>.<format>.twig
2. index.<format>.twig
3. home.<format>.twig
4. list.<format>.twig
5. _default/<layout>.<format>.twig
6. _default/index.<format>.twig
7. _default/home.<format>.twig
8. _default/list.<format>.twig
9. _default/page.<format>.twig

Type page

1. <section>/<layout>.<format>.twig
2. <layout>.<format>.twig
3. <section>/page.<format>.twig
4. _default/<layout>.<format>.twig
5. page.<format>.twig
6. _default/page.<format>.twig

Type section

1. <layout>.<format>.twig
2. <section>/index.<format>.twig
3. <section>/list.<format>.twig
4. section/<section>.<format>.twig
5. <parent>/index.<format>.twig, <parent>/list.<format>.twig and section/<parent>.<format>.twig, for each parent section of a sub-section (nearest first)
6. _default/section.<format>.twig
7. list.<format>.twig
8. _default/list.<format>.twig

Type vocabulary

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

Type term

1. taxonomy/<plural>/<term>.<format>.twig
2. taxonomy/<singular>.<format>.twig
3. term.<format>.twig
4. _default/term.<format>.twig
5. _default/list.<format>.twig

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, a menu entry, an asset, a page ID or a path.

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

Examples:

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

html

Creates an HTML element from an asset (or an array of assets with custom attributes).

{{ html(asset, {attributes}, {options}) }}
{# dedicated functions for each common type of asset #}
{{ css(asset) }}
{{ js(asset) }}
{{ image(asset) }}
{{ audio(asset) }}
{{ video(asset) }}

Examples:

{# CSS with an attribute #}
{{ html(asset('print.css'), {media: 'print'}) }}
{# CSS with an attribute and an option #}
{{ html(asset('styles.css'), {title: 'Main theme'}, {preload: true}) }}
{# Array of assets with media query #}
{{ html([
  {asset: asset('css/style.css')},
  {asset: asset('css/style-dark.css'), attributes: {media: '(prefers-color-scheme: dark)'}}
]) }}
{# JavaScript #}
{{ html(asset('script.js')) }}
{# image without specific attributes nor options #}
{{ html(asset('image.png')) }}
{# image with specific attributes, responsive images and alternative formats #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {responsive: true, formats: ['avif', 'webp']}) }}
{# image with responsive pixels density images #}
{{ html(asset('image.jpg'), options={responsive: 'density'}, attributes={width: 256}) }}
{# image with a Low-Quality Image Placeholder #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {placeholder: 'lqip'}) }}
{# Audio #}
{{ html(asset('audio.mp3')) }}
{# Video #}
{{ html(asset('video.mp4')) }}

readtime

Determines read time of a text, in minutes.

{{ readtime(value) }}

Example:

{{ readtime(page.content) }} min

hash

Calculates the hash of an object, an array or a string with a given algorithm.

{{ hash(value, algorithm) }}

algorithm can be any algorithm supported by PHP's hash() function (e.g.: md5, sha256, etc.). Default is xxh128.

Example:

{{ hash('my string', 'sha256') }}

cache_key

Calculates a cache key for fragments cache based on a name and an optional value.

{% cache cache_key(name, value) %}
  {# cacheable content #}
{% endcache %}

The function adds a hash of the value (could be a string, an array or an object) to the name (and the current language and build ID to be sure the generated cache key is unique) so if the value is changed the cache key is changed too and the cache is automatically cleared.

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 »

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 built-in variables and those set in the configuration.

Example:

title: "My amazing website!"

Can be displayed in a template with:

{{ site.title }}

site.menus

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

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

Information about the current language.

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)
• type: media type (e.g.: image)
• subtype: media sub type (e.g.: image/jpeg)
• exif: image EXIF data (array)
• audio: Mp3Info object
• video: array of basic video information (duration in seconds, width and height)

site.data

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

Examples:

• data/authors.yml : site.data.authors
• data/authors.fr.yml : site.data.authors (if site.language = "fr")
• data/galleries/gallery-1.json : site.data.galleries['gallery-1']

page

The page variable contains built-in variables of a page and those set in the front matter.

Nested sections

In a nested sections context, page.parent, page.ancestors, page.sections and page.toplevel help you build navigation.

Breadcrumb (from the home page to the current page):

<nav aria-label="breadcrumb">
  <ul>
    <li><a href="{{ url(site.home) }}">{{ site.title }}</a></li>
    {% for section in page.ancestors|reverse %}
    <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
    {% endfor %}
    {% if page.id != site.home %}
    <li><a href="{{ url(page) }}" aria-current="page">{{ page.title }}</a></li>
    {% endif %}
  </ul>
</nav>

Sub-sections menu (immediate descendant sections of the current section):

{% if page.sections|length %}
<ul>
  {% for section in page.sections|sort_by_title %}
  <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
  {% endfor %}
</ul>
{% endif %}

Main navigation limited to top level sections (from any page):

<nav>
  {% for section in site.page(site.home).sections|sort_by_title %}
  <a href="{{ url(section) }}">{{ section.title }}</a>
  {% endfor %}
</nav>

Link to the parent section:

{% if page.parent %}
<a href="{{ url(page.parent) }}">← {{ page.parent.title }}</a>
{% endif %}

page.<prev/next>

Navigation between pages within the same section, sorted according to the section's sortby (chronological order for dates).

With sub-sections, navigation follows the sections tree: the pages of a top level Section and of all its sub-sections are chained, each sub-section (its index page) being placed among the pages of its parent Section and followed by its own pages.

Example:

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

page.paginator

Paginator helps you build navigation for list pages: homepage, sections, and taxonomies.

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

Page /<plural>/ (e.g.: /categories/).

Each term of page.terms provides term.id (term ID, e.g.: categories/php), term.name (term name, e.g.: PHP) and the number of its pages with term|length.

Term

Page /<plural>/<term>/ (e.g.: /categories/php/).

Taxonomy example

Configuration:

taxonomies:
  categories: category

Page front matter:

---
categories: ["Data Sovereignty"]
---

List of terms (/categories/), in layouts/taxonomy/categories.html.twig:

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  <ul>
  {% for term in page.terms %}
    <li><a href="{{ url(term.id) }}">{{ term.name }}</a> ({{ term|length }})</li>
  {% endfor %}
  </ul>
{% endblock %}

List of pages of a term (/categories/data-sovereignty/), in layouts/taxonomy/category.html.twig:

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  {% for p in page.paginator.pages ?? page.pages %}
    <article>
      <h2><a href="{{ url(p) }}">{{ p.title }}</a></h2>
    </article>
  {% endfor %}
  <a href="{{ url(page.plural) }}">All {{ page.plural }}</a>
{% endblock %}

Links to the terms of the current page, in a page template:

{% for category in page.categories ?? [] %}
  <a href="{{ url('categories/' ~ category) }}">{{ category }}</a>
{% endfor %}

cecil

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

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

toc

Extracts only headings matching the given selectors (h2, h3, etc.), or those defined in config pages.body.toc if not specified.
The format parameter defines the output format: html or json.
The url parameter is used to build links to headings.

{{ markdown|toc(format, selectors, url) }}

Examples:

{{ page.body|toc }}
{{ page.body|toc('html') }}
{{ page.body|toc(selectors=['h2']) }}
{{ page.body|toc(url=url(page)) }}

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

u

The u filter wraps a text in a Unicode object (a Symfony UnicodeString instance) that exposes methods to "manipulate" the string.

Example:

{{ 'cecil_string with twig'|u.camel.title }}

CecilStringWithTwig

singular

The singular filter transforms a given noun in its plural form into its singular version.

{{ string|singular(locale)}}

Example:

{# English (en) rules are used by default #}
{{ 'partitions'|singular }}

partition

{{ 'partitions'|singular('fr') }}

partition

plural

The plural filter transforms a given noun in its singular form into its plural version.

{{ string|plural(locale)}}

Example:

{# English (en) rules are used by default #}
{{ 'animal'|plural }}

animals

{{ 'animal'|plural('fr') }}

animaux

excerpt

Truncates a string and appends suffix.

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

Examples:

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

excerpt_html

Reads characters before or after <!-- excerpt --> or <!-- break --> tag.
See Content documentation for details.

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

Examples:

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

highlight

Highlights a code string with highlight.php.

{{ code|highlight(language) }}

Examples:

{{ '<?php echo $highlighted->value; ?>'|highlight('php') }}

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

Cecil provides a components logic to give you the power making reusable template "units".

Components syntax

Components are just Twig templates stored in the components/ subdirectory and can be used anywhere in your templates:

{# /components/button.twig #}
<button {{ attributes.merge({class: 'rounded px-4'}) }}>
    {{ slot }}
</button>

The slot variable is any content you will add between the opening and the close tag.

To reach a component you need to use the dedicated tag x followed by : and the filename of your component without extension:

{# /index.twig #}
{% x:button with {class: 'text-white'} %}
    <strong>Click me</strong>
{% endx %}

It will render:

<button class="text-white rounded px-4">
    <strong>Click me</strong>
</button>

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>.<extension> and stored in the translations directory.
Supported file extensions are defined by each translation format in layouts.translations.formats.

The locale code (e.g.: fr_FR) of a language is defined in the languages entries of the configuration.

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.

Cecil uses a cache system to speed up the generation process, it can be disabled or cleared.

There are three cache types involved in template rendering: templates, assets, and translations.

Clear cache

You can clear the cache with the following commands:

php cecil.phar cache:clear               # clear all caches
php cecil.phar cache:clear:assets        # clear assets cache
php cecil.phar cache:clear:templates     # clear templates cache
php cecil.phar cache:clear:translations  # clear translations cache

Fragments cache

Cecil provides a way to cache parts of templates rendering to avoid re-rendering the same partial content multiple times.

To use fragments cache, you must wrap the content you want to cache with the cache tag.

{% cache 'unique-key' %}
  {# cacheable content #}
{% endcache %}

To clear fragments cache only, you can use the following command:

php cecil.phar cache:clear:templates --fragments

Disable cache

You can disable cache with the configuration.

Functions and filters

You can add custom functions and custom filters with a Twig extension.

Theme

It’s easy to build a theme, you just have to create a folder <theme> with the following structure (like a website but without pages):

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