A page is a file made up of a front matter and a body.
\nThe front matter is a collection of variables (in key/value format) surrounded by ---.
Example:
\n\ntitle: \"The title\"\ndate: 2019-02-21\ntags: [tag 1, tag 2]\ncustomvar: \"Value of customvar\"\nBody is the main content of a page, it could be written in Markdown or in plain text.
\nExample:
\n# Header\n\n[toc]\n\n## Sub-Header 1\n\nLorem ipsum dolor [sit amet](https://example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n<!-- excerpt -->\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n\n## Sub-Header 2\n\n![Description](/image.jpg \"Title\")\n\n## Sub-Header 3\n\n:::tip\nThis is advice.\n:::The filename can contain a prefix to define date or weight variables of the page (used by sortby).
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:
\nIn « 2019-04-23_My blog post.md »:
\ndate of the page is « 2019-04-23 »title of the page is « My blog post »The weight prefix is used to set the sort order of the page, and must be a valid integer value.
\nExample:
\nIn « 1_The first project.md »:
\nweight of the page is « 1 »title of the page is « The first project »Some dedicated variables can be used in a custom Section (i.e.: <section>/index.md).
The order of pages in a Section can be changed.
\nAvailable values are:
\ndate: more recent firsttitle: alphabetic orderweight: lightest firstExample:
\n\nsortby: title\nMore options:
\n\nsortby:\n variable: date # \"date\", \"updated\", \"title\" or \"weight\"\n desc_title: false # used with \"date\" or \"updated\" variable value to sort by desc title order if items have the same date\n reverse: false # reversed if true\nThe global pagination configuration is used by default, but you can change it for a specific Section.
\nExample:
\n\npagination:\n max: 5\n path: \"page\"\nPagination can be disabled for a Section:
\n\npagination: false\nAny variables in cascade are added to the front matter of all sub pages.
Example:
\n\ncascade:\n banner: image.jpg\nSet circular to true to enable circular navigation with page.<prev/next>.
Example:
\n\ncircular: true\nA nested folder that explicitly contains an index.md file is turned into a sub-section of its parent Section.
<mywebsite>\n└─ pages\n └─ blog <- Section\n ├─ index.md\n ├─ post-1.md <- Page in Section \"blog\"\n └─ 2024 <- Sub-section (contains an \"index.md\")\n ├─ index.md\n └─ post-2.md <- Page in Section \"blog\" *and* sub-section \"blog/2024\"A sub-section:
\n/blog/2024/)blog/list.html.twig)blog/2024/06/)sortby), followed by its own pagesLike another section, Home page support sortby and pagination configuration.
Set a valid Section name in pagesfrom to use pages collection from this Section in Home page.
Example:
\n\npagesfrom: blog\nThe front matter can contains custom variables applied to the current page.
\nIt must be the first thing in the file and must be a valid YAML.
\n| Variable | \nDescription | \nDefault value | \nExample | \n
|---|---|---|---|
title | \nTitle | \nFile name without extension. | \nPost 1 | \n
layout | \nTemplate | \nSee Lookup rules. | \n404 | \n
date | \nCreation date | \nFile creation date (PHP DateTime object). | \n2019/04/15 | \n
section | \nSection | \nPage's Section. | \nblog | \n
path | \nPath | \nPage's path. | \nblog/post-1 | \n
slug | \nSlug | \nPage's slug. | \npost-1 | \n
published | \nPublished or not | \ntrue. | \nfalse | \n
draft | \nPublished or not | \nfalse. | \ntrue | \n
The updated variable is used to define the last modification date of a page.
Example:
\n\nupdated: 2026-02-02\nA page can be added to a menu.
\nThe 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:
\n\nmenu: main\n\nmenu: [main, navigation] # same page in multiple menus\n\nmenu:\n main:\n weight: 10\n navigation:\n weight: 20\n\ntitle: 'Our Expertise'\nmenu:\n main:\n weight: 15\n footer:\n weight: 15\n name: \"Expertise\" # override the entry name in this menu\nTaxonomy allows you to connect, relate and classify your website’s content.
\nIn Cecil, these terms are gathered within vocabularies.
Vocabularies are declared in the Configuration.
\ntags, categories, etc.).Development, PHP, etc.).Example:
\n\ntags: [\"Development\", \"PHP\"]\nCecil then generates, for each vocabulary:
\n/tags//tags/development/ and /tags/php/See templates lookup rules and taxonomy variables to customize those pages.
\nSchedules pages’ publication.
\nExample:
\nThe page will be published if current date is >= 2023-02-07:
\nschedule:\n publish: 2023-02-07This page is published if current date is <= 2022-04-28:
\nschedule:\n expiry: 2022-04-28As indicated by its name, the redirect variable is used to redirect a page to a dedicated URL.
Example:
\n\nredirect: \"https://arnaudligny.fr\"\nAlias is a redirection to the current page
\nExample:
\n\ntitle: \"About\"\nalias:\n - contact\nIn the previous example contact/ redirects to about/.
Defines the output format of the page.
\nAvailable formats are: html, atom, rss, json, xml, etc.
\nYou 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.
\nExample:
\n\noutput: [html, atom]\nA page with an external variable try to fetch the content of the pointed resource.
Example:
\n\nexternal: \"https://raw.githubusercontent.com/Cecilapp/Cecil/main/README.md\"\nSet excluded to true to hide a page from list pages (i.e.: Home page, Section, Sitemap, etc.).
Example:
\n\nexcluded: true\nCecil supports Markdown format, but also Markdown Extra.
\nCecil also provides extra features to enhance your content, see below.
\nWith Markdown Extra you can set an id, class and custom attributes on certain elements using an attribute block.
\nFor 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:
\n[Link to a path](/about/)\n[Link to a Markdown file](/about/)\n[Link to Cecil website](https://cecil.app)You can easily create a link to a page with the syntax [Page title](page:page-id).
Example:
\n[Link to a blog post](page:blog/post-1)By default external links have the following value for rel attribute: noopener noreferrer.
Example:
\n<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:
\n[CECIL : LE générateur de SITES STATIQUES en PHP](https://www.youtube.com/watch?v=ur8koU0iYvc){embed}Cecil can also create a video and audio HTML elements, through the file extension.
\nExample:
\n[Video file](video.mp4){embed controls poster=/images/video-test.png}\n[Audio file](song.mp3){embed controls}Is converted to:
\n<video src=\"/video.mp4\" controls poster=\"/images/video-test.png\" style=\"max-width:100%;height:auto;\"></video>\n<audio src=\"/song.mp3\" controls></audio>To add an image, use an exclamation mark (!) followed by alternative description in brackets ([]), and the path or URL to the image in parentheses (()).
\nYou can optionally add a title in quotation marks.
![Alternative description](/image.jpg \"Image title\")Cecil adds the attribute loading=\"lazy\" to each image.
Example:
\nIs converted to:
\n<img src=\"/image.jpg\" loading=\"lazy\">Cecil adds the attribute decoding=\"async\" to each image.
Example:
\nIs converted to:
\n<img src=\"/image.jpg\" decoding=\"async\">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:
\n{width=800}Is converted to:
\n<img src=\"/thumbnails/800/image.jpg\" width=\"800\" height=\"600\">If the formats option is defined, alternatives images are created and added.
Example:
\nCould be converted to:
\n<picture>\n <source srcset=\"/image.avif\" type=\"image/avif\">\n <source srcset=\"/image.webp\" type=\"image/webp\">\n <img src=\"/image.jpg\">\n</picture>If the responsive option is enabled, then all images in the body will be made responsive automatically.
Example:
\n{width=800}will be converted to:
\n<img src=\"/thumbnails/800/image.jpg\" width=\"800\" height=\"600\"\n srcset=\"/thumbnails/320/image.jpg 320w,\n /thumbnails/640/image.jpg 640w,\n /thumbnails/800/image.jpg 800w\"\n sizes=\"100vw\"\n>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:
\nassets:\n images:\n responsive:\n sizes:\n default: 100vw\n my_class: \"(max-width: 800px) 768px, 1024px\"{.my_class}You can set a default value to the class attribute of each image with the class option.
The optional title can be used to create a caption (figcaption) automatically by enabling the caption option.
Example:
\n![](/images/img.jpg \"Title\")Is converted to:
\n<figure>\n <img src=\"/image.jpg\" title=\"Title\">\n <figcaption>Title</figcaption>\n</figure>For translated pages, Cecil first looks for a language-suffixed file when resolving Markdown image paths.
\nExample:
\nWith a French page (fr), Cecil tries /images/cecil-logo.fr.png first, then falls back to /images/cecil-logo.png.
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.
\nThe placeholder attribute accepts two options:
color: display a colored background (based on image dominant color)lqip: Low-Quality Image PlaceholderExamples:
\n{placeholder=color}\n{placeholder=lqip}You can add a table of contents with the following Markdown syntax:
\n[toc]An excerpt can be defined in the body with one of those following tags: excerpt or break.
Example:
\nIntroduction.\n<!-- excerpt -->\nMain content.Then use the excerpt_html filter in your template.
Create a Note block (info, tips, important, etc.).
\nExample:
\n:::tip\n**Tip:** This is advice.\n:::Is converted to:
\n<aside class=\"note note-tip\">\n <p>\n <strong>Tip:</strong> This is advice.\n </p>\n</aside>Others examples:
\n\n\n\n\n\n\nCode block syntax highlighting is enabled by default with the pages.body.highlight option.
\nIf needed, you can disable it with:
\npages:\n body:\n highlight: falseExample:
\n\n```php\necho \"Hello world\";\n```\n\n
Is rendered to:
\necho \"Hello world\";Represents a range of text that has been added.
\n++text++Is converted to:
\n<ins>text</ins>If your pages are available in multiple languages there is 2 different ways to define it:
\nThis is the common way to translate a page from the main language to another language.
\nYou just need to duplicate the reference page and suffix it with the target language code (e.g.: fr).
Example:
\n├─ about.md # the reference page\n└─ about.fr.md # the french version (`fr`)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:
\n\nlanguage: fr\nEach translated page reference the pages in others languages.
\nThose pages collection is available in templates with the following variable:
\n{{ page.translations }}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.
\n--\nvar: 'value'\n---\nThe value of `var` is {{ page.var }}.