Table of contents

Templates

Cecil use Twig as template engine, so refer to the official documentation to know how to use it.

Organization

Templates should be stored in layouts/.

<mywebsite>
├─ content
├─ layouts
|  ├─ _default           <- Contains default templates
|  |  ├─ list.html.twig  <- Used by a "list" page type
|  |  └─ page.html.twig  <- Used by the "page" page type
|  └─ index.html.twig    <- Used by the "homepage" page type
└─ themes
   └─ <theme>            <- Custom theme
      ├─ layouts
      └─ ...

Lookup rules

Cecil searches for the layout to use for a given page in a defined order.

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 Taxonomy:

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

If page type is Terms:

  1. taxonomy/<singular>.terms.<format>.twig
  2. _default/terms.<format>.twig

Otherwise:

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

<format>: Output format (html by default)
<layout>: Custom layout set in front matter
<section>: Page’s section

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.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 [Ta, Tb]
page.categories Array of categories [Ca, Cb]
page.pages Subpages Collection
page.filepath File system path Blog/Post 1.md

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

Page taxonomy

Variables available in taxonomy and terms layouts.

Variable Description
page.singular Taxonomy name
page.plural Taxonomy name (plural form)
page.terms List of terms (array)

site

Contains all variables under site key in configuration, and those predefined variables:

Variable Description
site.menus Menus collection
site.pages All pages collection
site.pages.all All non virtual pages

site.menus

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)

With KEY is the identifier of the menu collection, ie: main.

cecil

Variable Description
cecil.url URL to the official website
cecil.version Current version
cecil.poweredby "Cecil v%s". %s = 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()

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

Minify a CSS or a Javascript file.

{{ minify('css/style.css') }}
{{ minify('js/script.js') }}

readtime()

Return read time, in minutes.

{{ readtime(page.content) }} min

toCSS()

Compile a SCSS file (Sass) to CSS.

{{ toCSS('style/style.scss') }}

hash()

Return the hash of a file with sha384.

{{ hash('style/style.css') }}

getenv()

Gets the value of an environment variable.

{{ getenv('VAR') }}

Filters

filterBy()

Filter a pages collection by variable name/value.

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

sortByDate

Sort a pages collection by date (last first).

{{ pages|sortByDate }}

sortByTitle

Sort a pages collection by title (alphabetically).

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