What's on this page

• Files organization
  • Kinds of templates
  • Naming convention
  • Built-in templates
• Lookup rules
  • Type homepage
  • Type page
  • Type section
  • Type vocabulary
  • Type term

Organization and lookup rules

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