https://cecil.app/documentation/content/ Cecil - Content 2026-10-07T22:48:52+00:00 Cecil https://cecil.app https://cecil.app/documentation/content/pages/ Pages and sections 2021-05-07T00:00:00+00:00 2026-10-06T00:00:00+00:00 Pages and sections

A page is a file made up of a front matter and a body.

Front matter

The front matter is a collection of variables (in key/value format) surrounded by ---.

Example:

---
title: "The title"
date: 2019-02-21
tags: [tag 1, tag 2]
customvar: "Value of customvar"
---

Body

Body is the main content of a page, it could be written in Markdown or in plain text.

Example:

# Header

[toc]

## Sub-Header 1

Lorem ipsum dolor [sit amet](https://example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<!-- excerpt -->
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Sub-Header 2

![Description](/image.jpg "Title")

## Sub-Header 3

:::tip
This is advice.
:::

File prefix

The filename can contain a prefix to define date or weight variables of the page (used by sortby).

date

The date prefix is used to set the date of the page, and must be a valid date format (i.e.: « YYYY-MM-DD »).

Example:

In « 2019-04-23_My blog post.md »:

  • the prefix is « 2019-04-23 »
  • the date of the page is « 2019-04-23 »
  • the title of the page is « My blog post »

weight

The weight prefix is used to set the sort order of the page, and must be a valid integer value.

Example:

In « 1_The first project.md »:

  • the prefix is « 1 »
  • the weight of the page is « 1 »
  • the title of the page is « The first project »

Section

Some dedicated variables can be used in a custom Section (i.e.: <section>/index.md).

sortby

The order of pages in a Section can be changed.

Available values are:

  • date: more recent first
  • title: alphabetic order
  • weight: lightest first

Example:

---
sortby: title
---

More options:

---
sortby:
  variable: date    # "date", "updated", "title" or "weight"
  desc_title: false # used with "date" or "updated" variable value to sort by desc title order if items have the same date
  reverse: false    # reversed if true
---

pagination

The global pagination configuration is used by default, but you can change it for a specific Section.

Example:

---
pagination:
  max: 5
  path: "page"
---

Pagination can be disabled for a Section:

---
pagination: false
---

cascade

Any variables in cascade are added to the front matter of all sub pages.

Example:

---
cascade:
  banner: image.jpg
---

circular

Set circular to true to enable circular navigation with page.<prev/next>.

Example:

---
circular: true
---

Sub-section

A nested folder that explicitly contains an index.md file is turned into a sub-section of its parent Section.

<mywebsite>
└─ pages
   └─ blog                 <- Section
      ├─ index.md
      ├─ post-1.md         <- Page in Section "blog"
      └─ 2024              <- Sub-section (contains an "index.md")
         ├─ index.md
         └─ post-2.md      <- Page in Section "blog" *and* sub-section "blog/2024"

A sub-section:

  • is a Section (same type, variables and layout resolution) available at its own URL (e.g.: /blog/2024/)
  • is rendered with the layouts of its parent Sections if it doesn't have its own (e.g.: blog/list.html.twig)
  • can be nested at any depth (e.g.: blog/2024/06/)
  • lists its own pages, and its pages also belong to each of their parent Sections
  • is not listed in its parent Section
  • is placed in the page.<prev/next> navigation of its parent Section (according to its sortby), followed by its own pages

Home page

Like another section, Home page support sortby and pagination configuration.

pagesfrom

Set a valid Section name in pagesfrom to use pages collection from this Section in Home page.

Example:

---
pagesfrom: blog
---
]]> https://cecil.app/documentation/content/front-matter/ Front matter 2021-05-07T00:00:00+00:00 2026-10-03T00:00:00+00:00 Front matter

The front matter can contains custom variables applied to the current page.

It must be the first thing in the file and must be a valid YAML.

Predefined variables

Variable Description Default value Example
title Title File name without extension. Post 1
layout Template See Lookup rules. 404
date Creation date File creation date (PHP DateTime object). 2019/04/15
section Section Page's Section. blog
path Path Page's path. blog/post-1
slug Slug Page's slug. post-1
published Published or not true. false
draft Published or not false. true

updated

The updated variable is used to define the last modification date of a page.

Example:

---
updated: 2026-02-02
---

A page can be added to a menu.

The entry name is the page title and the URL is the page path.

The same page can be added to multiple menus, and each entry's position can be set with the weight key (lowest first). The name key can be used to override the default entry name per menu.

Examples:

---
menu: main
---
---
menu: [main, navigation] # same page in multiple menus
---
---
menu:
  main:
    weight: 10
  navigation:
    weight: 20
---
---
title: 'Our Expertise'
menu:
  main:
    weight: 15
  footer:
    weight: 15
    name: "Expertise" # override the entry name in this menu
---

Taxonomy

Taxonomy allows you to connect, relate and classify your website’s content.
In Cecil, these terms are gathered within vocabularies.

Vocabularies are declared in the Configuration.

Vocabulary
A categorization of content (e.g.: tags, categories, etc.).
Term
A term is an item of a vocabulary (e.g.: Development, PHP, etc.).

Example:

---
tags: ["Development", "PHP"]
---

Cecil then generates, for each vocabulary:

  • a page listing its terms, e.g.: /tags/
  • a page per term listing its pages, e.g.: /tags/development/ and /tags/php/

See templates lookup rules and taxonomy variables to customize those pages.

Schedule

Schedules pages’ publication.

Example:

The page will be published if current date is >= 2023-02-07:

schedule:
  publish: 2023-02-07

This page is published if current date is <= 2022-04-28:

schedule:
  expiry: 2022-04-28

redirect

As indicated by its name, the redirect variable is used to redirect a page to a dedicated URL.

Example:

---
redirect: "https://arnaudligny.fr"
---

alias

Alias is a redirection to the current page

Example:

---
title: "About"
alias:
  - contact
---

In the previous example contact/ redirects to about/.

output

Defines the output format of the page.

Available formats are: html, atom, rss, json, xml, etc.
You can define one or more formats in an array.

I’s not required to define an output format, but if you do, it must be one of the available formats defined in the Configuration.

Example:

---
output: [html, atom]
---

external

A page with an external variable try to fetch the content of the pointed resource.

Example:

---
external: "https://raw.githubusercontent.com/Cecilapp/Cecil/main/README.md"
---

excluded

Set excluded to true to hide a page from list pages (i.e.: Home page, Section, Sitemap, etc.).

Example:

---
excluded: true
---
]]> https://cecil.app/documentation/content/markdown/ Markdown 2021-05-07T00:00:00+00:00 2026-10-03T00:00:00+00:00 Markdown

Cecil supports Markdown format, but also Markdown Extra.

Cecil also provides extra features to enhance your content, see below.

Attributes

With Markdown Extra you can set an id, class and custom attributes on certain elements using an attribute block.
For instance, put the desired attribute(s) after a header, a fenced code block, a link or an image at the end of the line inside curly brackets, like this:

## Header {#id .class attribute=value}

You can create a link with the syntax [Text](url), where url can be a path, a relative path to a Markdown file, an external URL, etc.

Example:

[Link to a path](/about/)
[Link to a Markdown file](/about/)
[Link to Cecil website](https://cecil.app)

Link to a page

You can easily create a link to a page with the syntax [Page title](page:page-id).

Example:

[Link to a blog post](page:blog/post-1)

External

By default external links have the following value for rel attribute: noopener noreferrer.

Example:

<a href="<url>" rel="noopener noreferrer">Link to another website</a>

You can change this behavior with pages.body.links.external options.

Cecil can try to turn a link into embedded content by using the {embed} attribute or by setting the global configuration option pages.body.links.embed.enabled to true.

Example:

[CECIL : LE générateur de SITES STATIQUES en PHP](https://www.youtube.com/watch?v=ur8koU0iYvc){embed}

Local video/audio files

Cecil can also create a video and audio HTML elements, through the file extension.

Example:

[Video file](video.mp4){embed controls poster=/images/video-test.png}
[Audio file](song.mp3){embed controls}

Is converted to:

<video src="/video.mp4" controls poster="/images/video-test.png" style="max-width:100%;height:auto;"></video>
<audio src="/song.mp3" controls></audio>

Images

To add an image, use an exclamation mark (!) followed by alternative description in brackets ([]), and the path or URL to the image in parentheses (()).
You can optionally add a title in quotation marks.

![Alternative description](/image.jpg "Image title")

Lazy loading

Cecil adds the attribute loading="lazy" to each image.

Example:

![](/image.jpg)

Is converted to:

<img src="/image.jpg" loading="lazy">

Decoding

Cecil adds the attribute decoding="async" to each image.

Example:

![](/image.jpg)

Is converted to:

<img src="/image.jpg" decoding="async">

Resize

Each image in the body can be resized automatically by setting a smaller width than the original one, with the extra attribute {width=X}.

Example:

![](/image.jpg){width=800}

Is converted to:

<img src="/thumbnails/800/image.jpg" width="800" height="600">

Formats

If the formats option is defined, alternatives images are created and added.

Example:

![](/image.jpg)

Could be converted to:

<picture>
  <source srcset="/image.avif" type="image/avif">
  <source srcset="/image.webp" type="image/webp">
  <img src="/image.jpg">
</picture>

Responsive

If the responsive option is enabled, then all images in the body will be made responsive automatically.

Example:

![](/image.jpg){width=800}

will be converted to:

<img src="/thumbnails/800/image.jpg" width="800" height="600"
  srcset="/thumbnails/320/image.jpg 320w,
          /thumbnails/640/image.jpg 640w,
          /thumbnails/800/image.jpg 800w"
  sizes="100vw"
>

The sizes attribute takes the value of the assets.images.responsive.sizes.default configuration option, but it can be changed by creating a new entry named after a class added to the image.

Example:

assets:
  images:
    responsive:
      sizes:
        default: 100vw
        my_class: "(max-width: 800px) 768px, 1024px"
![](/image.jpg){.my_class}

CSS class

You can set a default value to the class attribute of each image with the class option.

Caption

The optional title can be used to create a caption (figcaption) automatically by enabling the caption option.

Example:

![](/images/img.jpg "Title")

Is converted to:

<figure>
  <img src="/image.jpg" title="Title">
  <figcaption>Title</figcaption>
</figure>

Localized image

For translated pages, Cecil first looks for a language-suffixed file when resolving Markdown image paths.

Example:

![](/images/cecil-logo.png)

With a French page (fr), Cecil tries /images/cecil-logo.fr.png first, then falls back to /images/cecil-logo.png.

Placeholder

As images are typically heavier and slower resources, and they don’t block rendering, we should attempt to give users something to look at while they wait for the image to arrive.

The placeholder attribute accepts two options:

  1. color: display a colored background (based on image dominant color)
  2. lqip: Low-Quality Image Placeholder

Examples:

![](/images/img.jpg){placeholder=color}
![](/images/img.jpg){placeholder=lqip}

Table of contents

You can add a table of contents with the following Markdown syntax:

[toc]

Excerpt

An excerpt can be defined in the body with one of those following tags: excerpt or break.

Example:

Introduction.
<!-- excerpt -->
Main content.

Then use the excerpt_html filter in your template.

Notes

Create a Note block (info, tips, important, etc.).

Example:

:::tip
**Tip:** This is advice.
:::

Is converted to:

<aside class="note note-tip">
  <p>
    <strong>Tip:</strong> This is advice.
  </p>
</aside>

Others examples:

Syntax highlight

Code block syntax highlighting is enabled by default with the pages.body.highlight option.

If needed, you can disable it with:

pages:
  body:
    highlight: false

Example:

```php
echo "Hello world";
```

Is rendered to:

echo "Hello world";

Inserted text

Represents a range of text that has been added.

++text++

Is converted to:

<ins>text</ins>
]]> https://cecil.app/documentation/content/multilingual/ Multilingual 2021-05-07T00:00:00+00:00 2026-10-03T00:00:00+00:00 Multilingual

If your pages are available in multiple languages there is 2 different ways to define it:

Through file name

This is the common way to translate a page from the main language to another language.

You just need to duplicate the reference page and suffix it with the target language code (e.g.: fr).

Example:

├─ about.md    # the reference page
└─ about.fr.md # the french version (`fr`)

Through front matter

If you want to create a page in a language other than the main language, without it being a translation of an existing page, you can use the language variable in its front matter.

Example:

---
language: fr
---

Each translated page reference the pages in others languages.

Those pages collection is available in templates with the following variable:

{{ page.translations }}
]]> https://cecil.app/documentation/content/dynamic-content/ Dynamic content 2021-05-07T00:00:00+00:00 2026-10-03T00:00:00+00:00 Dynamic content

You can create dynamic content in a page by using the template_from_string Twig function.

{{ include(template_from_string(page.content, "dynamic content for page " ~ page.id)) }}

With this, you can use any page variable in the body of the page.

--
var: 'value'
---
The value of `var` is {{ page.var }}.
]]>