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