{ "version": "https://jsonfeed.org/version/1.1", "title": "Cecil - How to?", "home_page_url": "https://cecil-945.pages.dev/how-to/", "feed_url": "https://cecil-945.pages.dev/how-to/feed.json", "description": "Articles and tutorials for common Cecil tasks.", "icon": "https://cecil-945.pages.dev/favicon.7ff4b89eec6dad139a7d2d6561543285.png", "favicon": "https://cecil-945.pages.dev/thumbnails/64x/favicon.7ff4b89eec6dad139a7d2d6561543285.png", "language": "en", "items": [ { "id": "https://cecil-945.pages.dev/how-to/markdown-toc-notes/", "url": "https://cecil-945.pages.dev/how-to/markdown-toc-notes/", "title": "Add a table of contents and notes", "summary": "Enrich Cecil Markdown pages with a table of contents, note blocks and custom attributes.", "date_published": "2026-10-14T00:00:00+00:00","content_text": "Cecil extends Markdown with a few handy features for long pages: an automatic table of contents, note blocks and attributes on elements.\nInsert a table of contents\nAdd the [toc] tag where the table of contents should appear in the body of the page:\n[toc]\n\n## Installation\n### Requirements\n## Usage\nBy default, the table of contents is built from H2 and H3 headings. Change it in cecil.yml:\npages:\n body:\n toc: [h2, h3, h4]\nDisplay the table of contents in a template\nTo place the table of contents outside the content (e.g. in a sidebar), use the toc filter on the page body:\n<aside>\n {{ page.body|toc }}\n<\/aside>\n<article>\n {{ page.content }}\n<\/article>\nThe filter also accepts the headings to extract, e.g. {{ page.body|toc(selectors=['h2']) }}.\nAdd notes\nHighlight information with a note block:\n:::tip\n**Tip:** This is advice.\n:::\nIs converted to:\n<aside class=\"note note-tip\">\n <p>\n <strong>Tip:<\/strong> This is advice.\n <\/p>\n<\/aside>\nAvailable types are info, tip, important, warning and caution (or no type). Style them with the note and note-<type> CSS classes.\nAdd attributes\nSet an id, a class or any attribute on a heading, a fenced code block, a link or an image, inside curly brackets at the end of the line:\n## Installation {#install .highlighted}\nThe #install id gives a stable anchor to link to: [See installation](#install).\nFor an inline element, like a link, add a line break after the closing brace.\nSee the documentation of the table of contents, notes, attributes and the toc filter.", "content_html": "

Cecil extends Markdown with a few handy features for long pages: an automatic table of contents, note blocks and attributes on elements.

\n

Insert a table of contents

\n

Add the [toc] tag where the table of contents should appear in the body of the page:

\n
[toc]\n\n## Installation\n### Requirements\n## Usage
\n

By default, the table of contents is built from H2 and H3 headings. Change it in cecil.yml:

\n
pages:\n  body:\n    toc: [h2, h3, h4]
\n

Display the table of contents in a template

\n

To place the table of contents outside the content (e.g. in a sidebar), use the toc filter on the page body:

\n
<aside>\n  {{ page.body|toc }}\n</aside>\n<article>\n  {{ page.content }}\n</article>
\n

The filter also accepts the headings to extract, e.g. {{ page.body|toc(selectors=['h2']) }}.

\n

Add notes

\n

Highlight information with a note block:

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

Is converted to:

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

Available types are info, tip, important, warning and caution (or no type). Style them with the note and note-<type> CSS classes.

\n

Add attributes

\n

Set an id, a class or any attribute on a heading, a fenced code block, a link or an image, inside curly brackets at the end of the line:

\n
## Installation {#install .highlighted}
\n

The #install id gives a stable anchor to link to: [See installation](#install).

\n\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/content-redirect-alias/", "url": "https://cecil-945.pages.dev/how-to/content-redirect-alias/", "title": "Redirect old URLs", "summary": "Keep old links working in Cecil with the redirect and alias front matter variables.", "date_published": "2026-10-13T00:00:00+00:00","content_text": "When a page moves or is renamed, its old URL should not lead to a 404 error. Cecil provides two front matter variables to handle this: alias and redirect.\nRedirect old URLs to a page\nThe alias variable lists the old paths of the current page. Each of them redirects to the page:\n---\ntitle: About\nalias:\n - contact\n - about-us\n---\nIn this example, \/contact\/ and \/about-us\/ redirect to \/about\/.\nRedirect a page to another URL\nThe redirect variable turns a page into a redirection to the given URL, internal or external:\n---\ntitle: Old documentation\nredirect: \"https:\/\/cecil.app\/documentation\/\"\n---\nWithout a Markdown file\nIf the old page has no content anymore, declare it as a virtual page in cecil.yml:\npages:\n virtual:\n - path: code\n redirect: https:\/\/github.com\/Cecilapp\/Cecil\nGenerated pages\nFor each alias and each redirection, Cecil renders a page with the built-in redirect.html.twig template. It contains:\n\na <link rel=\"canonical\"> to the target URL\na <meta name=\"robots\" content=\"noindex\"> tag, so search engines don’t index it\na <meta http-equiv=\"refresh\"> tag and a JavaScript redirection\na fallback link for visitors\n\nTo customize this page, create your own layouts\/redirect.html.twig template: it takes precedence over the built-in one.\nSee the documentation of the redirect and alias variables.", "content_html": "

When a page moves or is renamed, its old URL should not lead to a 404 error. Cecil provides two front matter variables to handle this: alias and redirect.

\n

Redirect old URLs to a page

\n

The alias variable lists the old paths of the current page. Each of them redirects to the page:

\n
---\ntitle: About\nalias:\n  - contact\n  - about-us\n---
\n

In this example, /contact/ and /about-us/ redirect to /about/.

\n

Redirect a page to another URL

\n

The redirect variable turns a page into a redirection to the given URL, internal or external:

\n
---\ntitle: Old documentation\nredirect: \"https://cecil.app/documentation/\"\n---
\n

Without a Markdown file

\n

If the old page has no content anymore, declare it as a virtual page in cecil.yml:

\n
pages:\n  virtual:\n    - path: code\n      redirect: https://github.com/Cecilapp/Cecil
\n

Generated pages

\n

For each alias and each redirection, Cecil renders a page with the built-in redirect.html.twig template. It contains:

\n\n\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/config-environments/", "url": "https://cecil-945.pages.dev/how-to/config-environments/", "title": "Use different settings per environment", "summary": "Override the Cecil configuration per environment with CECIL_ environment variables and extra config files.", "date_published": "2026-10-12T00:00:00+00:00","content_text": "Your local site and your production site rarely share the same settings: base URL, debug mode, output directory… Cecil lets you keep a single cecil.yml and override it per environment.\nKeep production values in cecil.yml\ntitle: \"My site\"\nbaseurl: https:\/\/example.com\/\ndebug: false\nOverride with extra config files\nCreate a file with only the keys to change, for example config\/dev.yml:\nbaseurl: http:\/\/localhost:8000\/\ndebug: true\nThen load it with the --config option, available with the build and serve commands:\nphp cecil.phar serve --config=config\/dev.yml\nYou can pass several files, separated by commas. They are merged in order after cecil.yml, so each file overrides the previous ones:\nphp cecil.phar build --config=config\/prod.yml,config\/local.yml\nOverride with environment variables\nAny configuration key can be set with an environment variable prefixed with CECIL_, in uppercase. Nested keys are separated with an underscore (e.g. CECIL_OUTPUT_DIR sets output.dir):\nexport CECIL_BASEURL=\"https:\/\/staging.example.com\/\"\nexport CECIL_DEBUG=true\nphp cecil.phar build\nCecil also loads a .env file from the site root, if it exists (variables already defined by the system are preserved):\nCECIL_BASEURL=\"http:\/\/localhost:8000\/\"\nCECIL_DEBUG=true\nEnvironment variables are applied on top of the configuration files, which makes them handy in CI, for example:\n# .gitlab-ci.yml\npages:\n variables:\n CECIL_ENV: production\n CECIL_OUTPUT_DIR: public\nRead the environment in templates\nUse the getenv function to adapt templates, for example to include analytics in production only:\n{% if getenv('CECIL_ENV') == 'production' %}\n {{ include('partials\/analytics.html.twig') }}\n{% endif %}\nThe site.debug variable tells you if debug mode is enabled:\n{% if site.debug %}{{ dump(page) }}{% endif %}\nSee the documentation for overriding the configuration, the debug option and the getenv function.", "content_html": "

Your local site and your production site rarely share the same settings: base URL, debug mode, output directory… Cecil lets you keep a single cecil.yml and override it per environment.

\n

Keep production values in cecil.yml

\n
title: \"My site\"\nbaseurl: https://example.com/\ndebug: false
\n

Override with extra config files

\n

Create a file with only the keys to change, for example config/dev.yml:

\n
baseurl: http://localhost:8000/\ndebug: true
\n

Then load it with the --config option, available with the build and serve commands:

\n
php cecil.phar serve --config=config/dev.yml
\n

You can pass several files, separated by commas. They are merged in order after cecil.yml, so each file overrides the previous ones:

\n
php cecil.phar build --config=config/prod.yml,config/local.yml
\n

Override with environment variables

\n

Any configuration key can be set with an environment variable prefixed with CECIL_, in uppercase. Nested keys are separated with an underscore (e.g. CECIL_OUTPUT_DIR sets output.dir):

\n
export CECIL_BASEURL=\"https://staging.example.com/\"\nexport CECIL_DEBUG=true\nphp cecil.phar build
\n

Cecil also loads a .env file from the site root, if it exists (variables already defined by the system are preserved):

\n
CECIL_BASEURL=\"http://localhost:8000/\"\nCECIL_DEBUG=true
\n

Environment variables are applied on top of the configuration files, which makes them handy in CI, for example:

\n
# .gitlab-ci.yml\npages:\n  variables:\n    CECIL_ENV: production\n    CECIL_OUTPUT_DIR: public
\n

Read the environment in templates

\n

Use the getenv function to adapt templates, for example to include analytics in production only:

\n
{% if getenv('CECIL_ENV') == 'production' %}\n  {{ include('partials/analytics.html.twig') }}\n{% endif %}
\n

The site.debug variable tells you if debug mode is enabled:

\n
{% if site.debug %}{{ dump(page) }}{% endif %}
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/templates-assets-scss/", "url": "https://cecil-945.pages.dev/how-to/templates-assets-scss/", "title": "Compile, minify and fingerprint CSS and JavaScript", "summary": "Process Sass, CSS and JavaScript files in Cecil templates with the asset function and its filters.", "date_published": "2026-10-11T00:00:00+00:00","content_text": "Cecil can compile Sass files, minify CSS and JavaScript, and add a content hash to file names (cache busting) directly from your templates, without any external build tool.\nConfigure assets processing\nSource files are stored in the assets\/ directory. Processing is enabled by default and can be tuned in cecil.yml:\nassets:\n compile:\n style: compressed # `expanded` or `compressed`\n import: [sass, scss] # imported paths\n minify: true # minifies CSS and JS\n fingerprint: true # adds content hash to file names\nLoad a stylesheet\nCreate an asset from a Sass file, compile it with to_css and render the <link> element with the html function:\n{{ html(asset('css\/styles.scss')|to_css|minify) }}\nFilters can be chained to control each step explicitly, which is useful if a feature is disabled globally:\n{{ asset('css\/styles.scss')|to_css|minify|fingerprint }}\nBundle JavaScript files\nPass an array of paths to create a single bundle, with a custom file name:\n{{ html(asset(['js\/menu.js', 'js\/search.js'], {filename: 'scripts.js'})) }}\nOptions can also be set per asset, for example to keep a remote file untouched:\n{{ html(asset('https:\/\/cdnjs.cloudflare.com\/ajax\/libs\/anchor-js\/4.3.1\/anchor.min.js', {minify: false})) }}\nAdd Subresource Integrity\nUse the integrity function (or the integrity attribute of the asset) to generate a sha384 hash:\n{% set styles = asset('css\/styles.scss')|to_css %}\n<link rel=\"stylesheet\" href=\"{{ url(styles) }}\" integrity=\"{{ integrity(styles) }}\" crossorigin=\"anonymous\">\nInline critical CSS\nOutput the content of an asset with the inline filter:\n<style>{{ asset('css\/critical.scss')|to_css|minify|inline }}<\/style>\nFor a few lines of styles written directly in the template, use the scss_to_css and minify_css filters:\n<style>\n{% apply scss_to_css|minify_css %}\n $color: #fcfcfc;\n body {\n background-color: $color;\n }\n{% endapply %}\n<\/style>\nSee the documentation of the asset function, the filters and the assets configuration.", "content_html": "

Cecil can compile Sass files, minify CSS and JavaScript, and add a content hash to file names (cache busting) directly from your templates, without any external build tool.

\n

Configure assets processing

\n

Source files are stored in the assets/ directory. Processing is enabled by default and can be tuned in cecil.yml:

\n
assets:\n  compile:\n    style: compressed    # `expanded` or `compressed`\n    import: [sass, scss] # imported paths\n  minify: true           # minifies CSS and JS\n  fingerprint: true      # adds content hash to file names
\n

Load a stylesheet

\n

Create an asset from a Sass file, compile it with to_css and render the <link> element with the html function:

\n
{{ html(asset('css/styles.scss')|to_css|minify) }}
\n

Filters can be chained to control each step explicitly, which is useful if a feature is disabled globally:

\n
{{ asset('css/styles.scss')|to_css|minify|fingerprint }}
\n

Bundle JavaScript files

\n

Pass an array of paths to create a single bundle, with a custom file name:

\n
{{ html(asset(['js/menu.js', 'js/search.js'], {filename: 'scripts.js'})) }}
\n

Options can also be set per asset, for example to keep a remote file untouched:

\n
{{ html(asset('https://cdnjs.cloudflare.com/ajax/libs/anchor-js/4.3.1/anchor.min.js', {minify: false})) }}
\n

Add Subresource Integrity

\n

Use the integrity function (or the integrity attribute of the asset) to generate a sha384 hash:

\n
{% set styles = asset('css/styles.scss')|to_css %}\n<link rel=\"stylesheet\" href=\"{{ url(styles) }}\" integrity=\"{{ integrity(styles) }}\" crossorigin=\"anonymous\">
\n

Inline critical CSS

\n

Output the content of an asset with the inline filter:

\n
<style>{{ asset('css/critical.scss')|to_css|minify|inline }}</style>
\n

For a few lines of styles written directly in the template, use the scss_to_css and minify_css filters:

\n
<style>\n{% apply scss_to_css|minify_css %}\n  $color: #fcfcfc;\n  body {\n    background-color: $color;\n  }\n{% endapply %}\n</style>
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/content-taxonomies/", "url": "https://cecil-945.pages.dev/how-to/content-taxonomies/", "title": "Organize pages with tags and categories", "summary": "Classify Cecil pages with taxonomies like tags and categories, and customize their list pages.", "date_published": "2026-10-10T00:00:00+00:00","content_text": "Taxonomies let you classify pages with terms (e.g. PHP) grouped in vocabularies (e.g. tags). Cecil then generates a page per vocabulary and a page per term.\nDeclare vocabularies\nVocabularies are declared in cecil.yml, paired by plural and singular names:\ntaxonomies:\n categories: category\n tags: tag\nThere are no default vocabularies: you must declare them to use them.\nClassify pages\nAdd terms in the front matter of your pages, using the plural name of the vocabulary:\n---\ntitle: My first post\ncategories: [\"Development\"]\ntags: [\"PHP\", \"Static site\"]\n---\nCecil generates:\n\n\/tags\/: the list of the terms of the vocabulary\n\/tags\/php\/ and \/tags\/static-site\/: the list of the pages of each term\n\nCustomize the list of terms\nThe vocabulary template is named after the plural, e.g. layouts\/taxonomy\/tags.html.twig:\n{% extends 'page.html.twig' %}\n\n{% block content %}\n <h1>{{ page.title }}<\/h1>\n <ul>\n {% for term in page.terms %}\n <li><a href=\"{{ url(term.id) }}\">{{ term.name }}<\/a> ({{ term|length }})<\/li>\n {% endfor %}\n <\/ul>\n{% endblock %}\nCustomize the pages of a term\nThe term template is named after the singular, e.g. layouts\/taxonomy\/tag.html.twig:\n{% extends 'page.html.twig' %}\n\n{% block content %}\n <h1>{{ page.title }}<\/h1>\n {% for p in page.paginator.pages ?? page.pages %}\n <article>\n <h2><a href=\"{{ url(p) }}\">{{ p.title }}<\/a><\/h2>\n <\/article>\n {% endfor %}\n <a href=\"{{ url(page.plural) }}\">All {{ page.plural }}<\/a>\n{% endblock %}\nDisplay the terms of a page\nIn a page template, link each term to its page:\n{% for tag in page.tags ?? [] %}\n <a href=\"{{ url('tags\/' ~ tag) }}\">{{ tag }}<\/a>\n{% endfor %}\nOr use the built-in partial: {{ include('partials\/terms-list.html.twig', {vocabulary: 'tags'}) }}.\nSee the documentation of taxonomies configuration, templates lookup rules and taxonomy variables.", "content_html": "

Taxonomies let you classify pages with terms (e.g. PHP) grouped in vocabularies (e.g. tags). Cecil then generates a page per vocabulary and a page per term.

\n

Declare vocabularies

\n

Vocabularies are declared in cecil.yml, paired by plural and singular names:

\n
taxonomies:\n  categories: category\n  tags: tag
\n\n

Classify pages

\n

Add terms in the front matter of your pages, using the plural name of the vocabulary:

\n
---\ntitle: My first post\ncategories: [\"Development\"]\ntags: [\"PHP\", \"Static site\"]\n---
\n

Cecil generates:

\n\n

Customize the list of terms

\n

The vocabulary template is named after the plural, e.g. layouts/taxonomy/tags.html.twig:

\n
{% extends 'page.html.twig' %}\n\n{% block content %}\n  <h1>{{ page.title }}</h1>\n  <ul>\n  {% for term in page.terms %}\n    <li><a href=\"{{ url(term.id) }}\">{{ term.name }}</a> ({{ term|length }})</li>\n  {% endfor %}\n  </ul>\n{% endblock %}
\n

Customize the pages of a term

\n

The term template is named after the singular, e.g. layouts/taxonomy/tag.html.twig:

\n
{% extends 'page.html.twig' %}\n\n{% block content %}\n  <h1>{{ page.title }}</h1>\n  {% for p in page.paginator.pages ?? page.pages %}\n    <article>\n      <h2><a href=\"{{ url(p) }}\">{{ p.title }}</a></h2>\n    </article>\n  {% endfor %}\n  <a href=\"{{ url(page.plural) }}\">All {{ page.plural }}</a>\n{% endblock %}
\n

Display the terms of a page

\n

In a page template, link each term to its page:

\n
{% for tag in page.tags ?? [] %}\n  <a href=\"{{ url('tags/' ~ tag) }}\">{{ tag }}</a>\n{% endfor %}
\n

Or use the built-in partial: {{ include('partials/terms-list.html.twig', {vocabulary: 'tags'}) }}.

\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/templates-menus/", "url": "https://cecil-945.pages.dev/how-to/templates-menus/", "title": "Build a navigation menu", "summary": "Declare menus in Cecil configuration or front matter and render them in templates.", "date_published": "2026-10-09T00:00:00+00:00","content_text": "Cecil manages navigation menus as collections of entries (name, URL, weight) that you can declare in the configuration or directly in pages, then render anywhere in your templates.\nDeclare entries in configuration\nAdd a menus section in cecil.yml. Each menu (e.g.: main, footer) is a list of entries with a unique id:\nmenus:\n main:\n - id: about\n name: \"About\"\n url: \/about\/\n weight: 1\n footer:\n - id: github\n name: \"GitHub\"\n url: https:\/\/github.com\/Cecilapp\/Cecil\n weight: 99\nA main menu is automatically created with the home page entry and all sections entries.\nAdd a page from its front matter\nA page can add itself to one or more menus with the menu variable. The entry name is the page title and the URL is the page path:\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\n---\nOverride or disable an entry\nUse the page ID as id to override an existing entry, or enabled: false to remove it:\nmenus:\n main:\n - id: index\n name: \"Home\"\n weight: 1\n - id: about\n enabled: false\nRender the menu\nLoop over site.menus.<menu>, sorted by weight, and compare each entry ID with the current page ID to highlight the active item:\n<nav>\n <ul>\n {% for entry in site.menus.main|sort_by_weight %}\n <li>\n <a href=\"{{ url(entry.url) }}\"{% if entry.id == page.id %} aria-current=\"page\" class=\"active\"{% endif %}>{{ entry.name }}<\/a>\n <\/li>\n {% endfor %}\n <\/ul>\n<\/nav>\nA single entry can also be reached by its ID:\n{% if site.menus.main.about is defined %}\n <a href=\"{{ url(site.menus.main.about.url) }}\">{{ site.menus.main.about.name }}<\/a>\n{% endif %}\nCecil also provides a built-in partial: {{ include('partials\/navigation.html.twig', {menu: 'main'}) }}.\nSee the documentation of the menus configuration, the menu front matter variable and the site.menus variable.", "content_html": "

Cecil manages navigation menus as collections of entries (name, URL, weight) that you can declare in the configuration or directly in pages, then render anywhere in your templates.

\n

Declare entries in configuration

\n

Add a menus section in cecil.yml. Each menu (e.g.: main, footer) is a list of entries with a unique id:

\n
menus:\n  main:\n    - id: about\n      name: \"About\"\n      url: /about/\n      weight: 1\n  footer:\n    - id: github\n      name: \"GitHub\"\n      url: https://github.com/Cecilapp/Cecil\n      weight: 99
\n\n

Add a page from its front matter

\n

A page can add itself to one or more menus with the menu variable. The entry name is the page title and the URL is the page path:

\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\n---
\n

Override or disable an entry

\n

Use the page ID as id to override an existing entry, or enabled: false to remove it:

\n
menus:\n  main:\n    - id: index\n      name: \"Home\"\n      weight: 1\n    - id: about\n      enabled: false
\n

Render the menu

\n

Loop over site.menus.<menu>, sorted by weight, and compare each entry ID with the current page ID to highlight the active item:

\n
<nav>\n  <ul>\n  {% for entry in site.menus.main|sort_by_weight %}\n    <li>\n      <a href=\"{{ url(entry.url) }}\"{% if entry.id == page.id %} aria-current=\"page\" class=\"active\"{% endif %}>{{ entry.name }}</a>\n    </li>\n  {% endfor %}\n  </ul>\n</nav>
\n

A single entry can also be reached by its ID:

\n
{% if site.menus.main.about is defined %}\n  <a href=\"{{ url(site.menus.main.about.url) }}\">{{ site.menus.main.about.name }}</a>\n{% endif %}
\n\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/output-search-index/", "url": "https://cecil-945.pages.dev/how-to/output-search-index/", "title": "Add client-side search", "summary": "Add a client-side search to a Cecil static site with a JSON index of pages and a small JavaScript library.", "date_published": "2026-10-08T00:00:00+00:00","content_text": "A static site has no server-side search, but Cecil can generate a JSON index of your pages at build time. A few lines of JavaScript are then enough to search it in the browser.\nCreate the index page\nCreate a page whose only output format is json, with a dedicated layout:\npages\/search.md\n---\ntitle: Search index\nlayout: search\noutput: json\nexcluded: true\n---\nexcluded: true keeps this technical page out of list pages and the sitemap.\nWrite the JSON template\nFollowing the lookup rules, Cecil renders this page with layouts\/search.json.twig. Build an array of the showable pages, then encode it:\n{%- set index = [] -%}\n{%- for p in site.pages.showable|filter(p => p.type == 'page') -%}\n {%- set index = index|merge([{\n title: p.title,\n url: url(p),\n description: p.description|default(''),\n content: p.content|striptags|excerpt(300)\n }]) -%}\n{%- endfor -%}\n{{ index|json_encode(constant('JSON_UNESCAPED_UNICODE') b-or constant('JSON_UNESCAPED_SLASHES'))|raw }}\nAfter php cecil.phar build, the index is available at \/search.json.\nSee the output variable, the output formats and the url function documentation.\nSearch with Fuse.js\nAdd a search field to a template and load Fuse.js from a CDN to query the index:\n<input type=\"search\" id=\"search\" placeholder=\"Search…\">\n<ul id=\"results\"><\/ul>\n\n<script type=\"module\">\n import Fuse from 'https:\/\/cdn.jsdelivr.net\/npm\/fuse.js@7\/dist\/fuse.mjs';\n\n const index = await fetch('{{ url('search', {format: 'json'}) }}').then(r => r.json());\n const fuse = new Fuse(index, { keys: ['title', 'description', 'content'], threshold: 0.3 });\n const results = document.getElementById('results');\n\n document.getElementById('search').addEventListener('input', (e) => {\n results.replaceChildren(...fuse.search(e.target.value, { limit: 10 }).map(({ item }) => {\n const li = document.createElement('li');\n const a = document.createElement('a');\n a.href = item.url;\n a.textContent = item.title;\n li.append(a);\n return li;\n }));\n });\n<\/script>\nAlternative: Pagefind\nPagefind indexes the generated HTML files instead: no JSON template is needed. Run it after the build, on the output directory (_site by default):\nphp cecil.phar build\nnpx pagefind --site _site\nThen load its UI in a template:\n<link href=\"\/pagefind\/pagefind-ui.css\" rel=\"stylesheet\">\n<script src=\"\/pagefind\/pagefind-ui.js\"><\/script>\n<div id=\"search\"><\/div>\n<script>\n window.addEventListener('DOMContentLoaded', () => new PagefindUI({ element: '#search' }));\n<\/script>\nThe index is a regular page: to regenerate only JSON outputs, declare a subset and run php cecil.phar build --render-subset=<name>.", "content_html": "

A static site has no server-side search, but Cecil can generate a JSON index of your pages at build time. A few lines of JavaScript are then enough to search it in the browser.

\n

Create the index page

\n

Create a page whose only output format is json, with a dedicated layout:

\n

pages/search.md

\n
---\ntitle: Search index\nlayout: search\noutput: json\nexcluded: true\n---
\n

excluded: true keeps this technical page out of list pages and the sitemap.

\n

Write the JSON template

\n

Following the lookup rules, Cecil renders this page with layouts/search.json.twig. Build an array of the showable pages, then encode it:

\n
{%- set index = [] -%}\n{%- for p in site.pages.showable|filter(p => p.type == 'page') -%}\n  {%- set index = index|merge([{\n    title: p.title,\n    url: url(p),\n    description: p.description|default(''),\n    content: p.content|striptags|excerpt(300)\n  }]) -%}\n{%- endfor -%}\n{{ index|json_encode(constant('JSON_UNESCAPED_UNICODE') b-or constant('JSON_UNESCAPED_SLASHES'))|raw }}
\n

After php cecil.phar build, the index is available at /search.json.

\n\n

Search with Fuse.js

\n

Add a search field to a template and load Fuse.js from a CDN to query the index:

\n
<input type=\"search\" id=\"search\" placeholder=\"Search…\">\n<ul id=\"results\"></ul>\n\n<script type=\"module\">\n  import Fuse from 'https://cdn.jsdelivr.net/npm/fuse.js@7/dist/fuse.mjs';\n\n  const index = await fetch('{{ url('search', {format: 'json'}) }}').then(r => r.json());\n  const fuse = new Fuse(index, { keys: ['title', 'description', 'content'], threshold: 0.3 });\n  const results = document.getElementById('results');\n\n  document.getElementById('search').addEventListener('input', (e) => {\n    results.replaceChildren(...fuse.search(e.target.value, { limit: 10 }).map(({ item }) => {\n      const li = document.createElement('li');\n      const a = document.createElement('a');\n      a.href = item.url;\n      a.textContent = item.title;\n      li.append(a);\n      return li;\n    }));\n  });\n</script>
\n

Alternative: Pagefind

\n

Pagefind indexes the generated HTML files instead: no JSON template is needed. Run it after the build, on the output directory (_site by default):

\n
php cecil.phar build\nnpx pagefind --site _site
\n

Then load its UI in a template:

\n
<link href=\"/pagefind/pagefind-ui.css\" rel=\"stylesheet\">\n<script src=\"/pagefind/pagefind-ui.js\"></script>\n<div id=\"search\"></div>\n<script>\n  window.addEventListener('DOMContentLoaded', () => new PagefindUI({ element: '#search' }));\n</script>
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/deploy-github-pages/", "url": "https://cecil-945.pages.dev/how-to/deploy-github-pages/", "title": "Deploy to GitHub Pages with GitHub Actions", "summary": "Build and deploy a Cecil site to GitHub Pages automatically with the Cecil GitHub Action.", "date_published": "2026-10-07T00:00:00+00:00","content_text": "With the Cecil Action, every push to your repository builds the site and publishes it to GitHub Pages, with no server to manage.\nEnable GitHub Pages\nIn your repository, go to Settings → Pages and, under Build and deployment, set Source to GitHub Actions.\nAdd the workflow\nCreate the file .github\/workflows\/build-and-deploy.yml:\nname: Build and deploy to GitHub Pages\non:\n push:\n branches: [master, main]\n workflow_dispatch:\nconcurrency:\n group: pages\n cancel-in-progress: true\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout source\n uses: actions\/checkout@v6\n - name: Build site\n uses: Cecilapp\/Cecil-Action@v4\n deploy:\n needs: build\n permissions:\n pages: write\n id-token: write\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n runs-on: ubuntu-latest\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions\/deploy-pages@v5\nThe build job downloads Cecil, installs themes (if a composer.json file exists), builds the site and uploads the output directory as a Pages artifact. The deploy job then publishes it.\nBase URL\nYou don’t need to change baseurl in cecil.yml: the action builds the site with the URL provided by GitHub Pages (e.g. https:\/\/<user>.github.io\/<repository>\/), using the --baseurl option.\nCustomize the build\nThe action accepts the following optional inputs:\n - name: Build site\n uses: Cecilapp\/Cecil-Action@v4\n with:\n version: '9.6.2' # Cecil version (latest by default)\n install_themes: 'no' # skip themes installation (`yes` by default)\n options: '-v --drafts' # build command options (`-v` by default)\nTo speed up builds, you can also restore and save the .cache directory between runs: see the full workflow in the GitHub Pages deployment documentation, and the list of build options.", "content_html": "

With the Cecil Action, every push to your repository builds the site and publishes it to GitHub Pages, with no server to manage.

\n

Enable GitHub Pages

\n

In your repository, go to Settings → Pages and, under Build and deployment, set Source to GitHub Actions.

\n

Add the workflow

\n

Create the file .github/workflows/build-and-deploy.yml:

\n
name: Build and deploy to GitHub Pages\non:\n  push:\n    branches: [master, main]\n  workflow_dispatch:\nconcurrency:\n  group: pages\n  cancel-in-progress: true\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout source\n        uses: actions/checkout@v6\n      - name: Build site\n        uses: Cecilapp/Cecil-Action@v4\n  deploy:\n    needs: build\n    permissions:\n      pages: write\n      id-token: write\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    runs-on: ubuntu-latest\n    steps:\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v5
\n

The build job downloads Cecil, installs themes (if a composer.json file exists), builds the site and uploads the output directory as a Pages artifact. The deploy job then publishes it.

\n

Base URL

\n

You don’t need to change baseurl in cecil.yml: the action builds the site with the URL provided by GitHub Pages (e.g. https://<user>.github.io/<repository>/), using the --baseurl option.

\n

Customize the build

\n

The action accepts the following optional inputs:

\n
      - name: Build site\n        uses: Cecilapp/Cecil-Action@v4\n        with:\n          version: '9.6.2'       # Cecil version (latest by default)\n          install_themes: 'no'   # skip themes installation (`yes` by default)\n          options: '-v --drafts' # build command options (`-v` by default)
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/output-rss-json-feed/", "url": "https://cecil-945.pages.dev/how-to/output-rss-json-feed/", "title": "Publish an RSS or JSON feed", "summary": "Publish RSS, Atom or JSON feeds of your Cecil site with output formats and built-in templates.", "date_published": "2026-10-06T00:00:00+00:00","content_text": "Cecil renders feeds with output formats: by default, the home page, sections and taxonomy terms are already published in HTML and Atom (e.g. \/atom.xml, \/blog\/atom.xml). Add the rss or jsonfeed formats to publish RSS 2.0 or JSON Feed files too.\nEnable feeds for all list pages\nSet the formats applied to each page type with output.pagetypeformats:\noutput:\n pagetypeformats:\n homepage: [html, atom, rss, jsonfeed]\n section: [html, atom, rss, jsonfeed]\nCecil now generates rss.xml and feed.json next to each index.html of the home page and sections (e.g. \/blog\/rss.xml, \/blog\/feed.json).\nFormats are replaced, not merged: keep html in the list. See output.pagetypeformats and the list of default formats.\nEnable a feed for a single section\nTo publish a feed only for one section, use the output variable in the front matter of the section index page:\n---\ntitle: Blog\noutput: [html, rss]\n---\nAdvertise the feed\nIf your templates include the metatags partial, <link rel=\"alternate\"> tags pointing to the feeds of the current page are added automatically in the <head>.\nOtherwise, add the link yourself with the url() function and its format option:\n<link rel=\"alternate\" type=\"application\/rss+xml\" title=\"{{ site.title }}\" href=\"{{ url(page, {canonical: true, format: 'rss'}) }}\">\nCustomize the feed template\nFeeds are rendered by the built-in templates _default\/list.rss.twig, _default\/list.atom.twig and _default\/list.jsonfeed.twig. Following the lookup rules, create layouts\/list.rss.twig (all list pages) or layouts\/blog\/list.rss.twig (blog section only) to override them.\nYou can extend the built-in template and redefine only the item block, for example to publish an excerpt instead of the full content:\n{% extends '_default\/list.rss.twig' %}\n\n{% block item %}\n <guid>{{ url(item, {canonical: true}) }}<\/guid>\n <title>{{ item.title|e }}<\/title>\n <pubDate>{{ item.date|date('r') }}<\/pubDate>\n <link>{{ url(item, {canonical: true}) }}<\/link>\n <description><![CDATA[{{ item.content|excerpt_html }}]]><\/description>\n{% endblock %}\nSet baseurl in cecil.yml: feeds use absolute URLs.\nThe RSS feed can also be styled in browsers by enabling the xsl\/rss default page:\npages:\n default:\n xsl\/rss:\n published: true", "content_html": "

Cecil renders feeds with output formats: by default, the home page, sections and taxonomy terms are already published in HTML and Atom (e.g. /atom.xml, /blog/atom.xml). Add the rss or jsonfeed formats to publish RSS 2.0 or JSON Feed files too.

\n

Enable feeds for all list pages

\n

Set the formats applied to each page type with output.pagetypeformats:

\n
output:\n  pagetypeformats:\n    homepage: [html, atom, rss, jsonfeed]\n    section: [html, atom, rss, jsonfeed]
\n

Cecil now generates rss.xml and feed.json next to each index.html of the home page and sections (e.g. /blog/rss.xml, /blog/feed.json).

\n\n

Enable a feed for a single section

\n

To publish a feed only for one section, use the output variable in the front matter of the section index page:

\n
---\ntitle: Blog\noutput: [html, rss]\n---
\n

Advertise the feed

\n

If your templates include the metatags partial, <link rel=\"alternate\"> tags pointing to the feeds of the current page are added automatically in the <head>.

\n

Otherwise, add the link yourself with the url() function and its format option:

\n
<link rel=\"alternate\" type=\"application/rss+xml\" title=\"{{ site.title }}\" href=\"{{ url(page, {canonical: true, format: 'rss'}) }}\">
\n

Customize the feed template

\n

Feeds are rendered by the built-in templates _default/list.rss.twig, _default/list.atom.twig and _default/list.jsonfeed.twig. Following the lookup rules, create layouts/list.rss.twig (all list pages) or layouts/blog/list.rss.twig (blog section only) to override them.

\n

You can extend the built-in template and redefine only the item block, for example to publish an excerpt instead of the full content:

\n
{% extends '_default/list.rss.twig' %}\n\n{% block item %}\n      <guid>{{ url(item, {canonical: true}) }}</guid>\n      <title>{{ item.title|e }}</title>\n      <pubDate>{{ item.date|date('r') }}</pubDate>\n      <link>{{ url(item, {canonical: true}) }}</link>\n      <description><![CDATA[{{ item.content|excerpt_html }}]]></description>\n{% endblock %}
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/templates-pagination/", "url": "https://cecil-945.pages.dev/how-to/templates-pagination/", "title": "Paginate a list of pages", "summary": "Split long lists of pages (blog, sections, taxonomies) into several pages with Cecil pagination.", "date_published": "2026-10-05T00:00:00+00:00","content_text": "When a section contains many pages, Cecil can split its list into several pages (e.g.: \/blog\/, \/blog\/page\/2\/, \/blog\/page\/3\/, etc.) and give you a paginator to build the navigation links.\nConfigure pagination\nPagination is enabled by default for list pages (homepage, section and term), with 5 entries per page. Change it in cecil.yml:\npages:\n pagination:\n max: 10 # maximum number of entries per page\n path: page # path to the paginated page\nOverride it for a section\nSet the pagination variable in the front matter of the section index file (e.g.: pages\/blog\/index.md):\n---\ntitle: Blog\npagination:\n max: 20\n---\nOr disable it for this section only:\n---\npagination: false\n---\nDisplay the paginated pages\nIn the list template (e.g.: layouts\/blog\/list.html.twig), loop over page.paginator.pages and fall back to page.pages when pagination is disabled:\n{% for p in page.paginator.pages ?? page.pages %}\n <article>\n <h2><a href=\"{{ url(p) }}\">{{ p.title }}<\/a><\/h2>\n <time datetime=\"{{ p.date|date('c') }}\">{{ p.date|date('j M Y') }}<\/time>\n <\/article>\n{% endfor %}\nAdd navigation links\nPaginator links are page IDs, so use the url() function to create working links:\n{% if page.paginator %}\n<nav>\n {% if page.paginator.links.prev is defined %}\n <a href=\"{{ url(page.paginator.links.prev) }}\" rel=\"prev\">Previous<\/a>\n {% endif %}\n <span>Page {{ page.paginator.current }} of {{ page.paginator.count }}<\/span>\n {% if page.paginator.links.next is defined %}\n <a href=\"{{ url(page.paginator.links.next) }}\" rel=\"next\">Next<\/a>\n {% endif %}\n<\/nav>\n{% endif %}\nTo list every page number, iterate from 1 to page.paginator.count:\n{% if page.paginator %}\n<nav>\n {% for i in 1..page.paginator.count %}\n {% if i == page.paginator.current %}\n <span aria-current=\"page\">{{ i }}<\/span>\n {% elseif i == 1 %}\n <a href=\"{{ url(page.paginator.links.first) }}\">{{ i }}<\/a>\n {% else %}\n <a href=\"{{ url(page.paginator.links.path ~ '\/' ~ i) }}\">{{ i }}<\/a>\n {% endif %}\n {% endfor %}\n<\/nav>\n{% endif %}\nSee the documentation of the page.paginator variable, the pagination configuration and the section pagination variable.", "content_html": "

When a section contains many pages, Cecil can split its list into several pages (e.g.: /blog/, /blog/page/2/, /blog/page/3/, etc.) and give you a paginator to build the navigation links.

\n

Configure pagination

\n

Pagination is enabled by default for list pages (homepage, section and term), with 5 entries per page. Change it in cecil.yml:

\n
pages:\n  pagination:\n    max: 10    # maximum number of entries per page\n    path: page # path to the paginated page
\n

Override it for a section

\n

Set the pagination variable in the front matter of the section index file (e.g.: pages/blog/index.md):

\n
---\ntitle: Blog\npagination:\n  max: 20\n---
\n

Or disable it for this section only:

\n
---\npagination: false\n---
\n

Display the paginated pages

\n

In the list template (e.g.: layouts/blog/list.html.twig), loop over page.paginator.pages and fall back to page.pages when pagination is disabled:

\n
{% for p in page.paginator.pages ?? page.pages %}\n  <article>\n    <h2><a href=\"{{ url(p) }}\">{{ p.title }}</a></h2>\n    <time datetime=\"{{ p.date|date('c') }}\">{{ p.date|date('j M Y') }}</time>\n  </article>\n{% endfor %}
\n

Add navigation links

\n

Paginator links are page IDs, so use the url() function to create working links:

\n
{% if page.paginator %}\n<nav>\n  {% if page.paginator.links.prev is defined %}\n  <a href=\"{{ url(page.paginator.links.prev) }}\" rel=\"prev\">Previous</a>\n  {% endif %}\n  <span>Page {{ page.paginator.current }} of {{ page.paginator.count }}</span>\n  {% if page.paginator.links.next is defined %}\n  <a href=\"{{ url(page.paginator.links.next) }}\" rel=\"next\">Next</a>\n  {% endif %}\n</nav>\n{% endif %}
\n

To list every page number, iterate from 1 to page.paginator.count:

\n
{% if page.paginator %}\n<nav>\n  {% for i in 1..page.paginator.count %}\n    {% if i == page.paginator.current %}\n  <span aria-current=\"page\">{{ i }}</span>\n    {% elseif i == 1 %}\n  <a href=\"{{ url(page.paginator.links.first) }}\">{{ i }}</a>\n    {% else %}\n  <a href=\"{{ url(page.paginator.links.path ~ '/' ~ i) }}\">{{ i }}</a>\n    {% endif %}\n  {% endfor %}\n</nav>\n{% endif %}
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/content-multilingual/", "url": "https://cecil-945.pages.dev/how-to/content-multilingual/", "title": "Translate a site into multiple languages", "summary": "Translate pages, configuration and template strings of a Cecil site into multiple languages.", "date_published": "2026-10-04T00:00:00+00:00","content_text": "Cecil handles multilingual sites natively: declare the languages, add translated pages, then link them together and translate your templates.\nDeclare languages\nDefine the main language and the list of available languages in cecil.yml:\nlanguage: en\nlanguages:\n - code: en\n name: English\n locale: en_US\n - code: fr\n name: Français\n locale: fr_FR\n config:\n title: \"Mon site en français\"\nOptions stored under the config key of a language override the global ones (here the site title).\nTranslate a page\nDuplicate the reference page and suffix its file name with the language code:\npages\/\n├─ about.md # the reference page\n└─ about.fr.md # the french version\nUse the slug variable to translate the URL of the page:\n---\ntitle: À propos\nslug: a-propos\n---\nabout.md is published to \/about\/ and about.fr.md to \/fr\/a-propos\/.\nTo create a page that only exists in another language (not a translation), set language: fr in its front matter.\nLink translated pages\nEach page exposes its translations with page.translations. Add a language switcher to your template:\n{% for p in page.translations %}\n <a href=\"{{ url(p) }}\" hreflang=\"{{ p.language }}\">{{ site.language.name(p.language) }}<\/a>\n{% endfor %}\nYou can also include the built-in partial: {{ include('partials\/languages.html.twig') }}.\nTranslate template strings\nWrap texts with the trans tag or filter:\n{% trans %}Read more{% endtrans %}\n{{ 'Read more'|trans }}\nThen add a translation file named after the language locale in the translations directory:\n# translations\/messages.fr_FR.yaml\nRead more: Lire la suite\nExtract the strings of your templates with:\nphp cecil.phar util:translations:extract --locale=fr_FR --save\nSee the documentation of multilingual content, languages configuration and templates localization.", "content_html": "

Cecil handles multilingual sites natively: declare the languages, add translated pages, then link them together and translate your templates.

\n

Declare languages

\n

Define the main language and the list of available languages in cecil.yml:

\n
language: en\nlanguages:\n  - code: en\n    name: English\n    locale: en_US\n  - code: fr\n    name: Français\n    locale: fr_FR\n    config:\n      title: \"Mon site en français\"
\n

Options stored under the config key of a language override the global ones (here the site title).

\n

Translate a page

\n

Duplicate the reference page and suffix its file name with the language code:

\n
pages/\n├─ about.md    # the reference page\n└─ about.fr.md # the french version
\n

Use the slug variable to translate the URL of the page:

\n
---\ntitle: À propos\nslug: a-propos\n---
\n

about.md is published to /about/ and about.fr.md to /fr/a-propos/.

\n\n\n

Each page exposes its translations with page.translations. Add a language switcher to your template:

\n
{% for p in page.translations %}\n  <a href=\"{{ url(p) }}\" hreflang=\"{{ p.language }}\">{{ site.language.name(p.language) }}</a>\n{% endfor %}
\n

You can also include the built-in partial: {{ include('partials/languages.html.twig') }}.

\n

Translate template strings

\n

Wrap texts with the trans tag or filter:

\n
{% trans %}Read more{% endtrans %}\n{{ 'Read more'|trans }}
\n

Then add a translation file named after the language locale in the translations directory:

\n
# translations/messages.fr_FR.yaml\nRead more: Lire la suite
\n

Extract the strings of your templates with:

\n
php cecil.phar util:translations:extract --locale=fr_FR --save
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/templates-metatags/", "url": "https://cecil-945.pages.dev/how-to/templates-metatags/", "title": "Apply SEO features in templates", "summary": "Add Cecil SEO features to templates with the metatags partial.", "date_published": "2026-06-09T00:00:00+00:00","content_text": "Cecil exposes its SEO feature through the partials\/metatags.html.twig template. Include it in the <head> of your base template so every page automatically gets meta tags, canonical links, social cards, and structured data.\n<html lang=\"{{ site.language }}\">\n <head>\n <meta charset=\"utf-8\">\n {{ include('partials\/metatags.html.twig') }}\n <\/head>\n <body>\n ...\n <\/body>\n<\/html>\nThe partial reads page front matter first, then falls back to site configuration when needed. See the metatags configuration documentation for all available options.\nIf you need to override the default title or image, pass values directly to the partial:\n{{ include('partials\/metatags.html.twig', {title: 'Custom title', image: og_image}) }}", "content_html": "

Cecil exposes its SEO feature through the partials/metatags.html.twig template. Include it in the <head> of your base template so every page automatically gets meta tags, canonical links, social cards, and structured data.

\n
<html lang=\"{{ site.language }}\">\n  <head>\n    <meta charset=\"utf-8\">\n    {{ include('partials/metatags.html.twig') }}\n  </head>\n  <body>\n    ...\n  </body>\n</html>
\n

The partial reads page front matter first, then falls back to site configuration when needed. See the metatags configuration documentation for all available options.

\n

If you need to override the default title or image, pass values directly to the partial:

\n
{{ include('partials/metatags.html.twig', {title: 'Custom title', image: og_image}) }}
", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/markdown-performance-images/", "url": "https://cecil-945.pages.dev/how-to/markdown-performance-images/", "title": "Optimize images in Markdown", "summary": "Optimize Markdown images in Cecil with responsive sizes, formats, and lazy loading.", "date_published": "2025-06-01T00:00:00+00:00", "date_modified": "2025-06-02T00:00:00+00:00","content_text": "One of the most effective ways to improve the performance of your website is to optimize images.\nCecil can manage the following optimizations for images in Markdown, automatically:\n\nDimensions: Images dimensions are set to ensure proper layout and prevent layout shifts\nCompression: The image is compressed to reduce file size without significant loss of quality\nImage formats: Cecil generates AVIF and WebP formats for the image\nResponsive images: Cecil generates two different sizes of the image (based on the configuration) to serve the appropriate size for different devices\nLazy loading: The image is set to load lazily, meaning it will only load when it comes into the viewport\nDecoding: The image is set to decode asynchronously, improving the initial page load time\nPlaceholder: A color placeholder is used while the image is loading\n\nSee documentation for more details on the global assets configuration and the pages configuration.\nExample\nBellow an example with a PNG image 1920x1276 pixels.\n![A star forming region in the sky](..\/..\/assets\/arnaud-girault-IjEtFjxXweE-unsplash.jpg \"Photo by Arnaud Girault\"){placeholder=color}\n\n\n\n\n\n\nPhoto by Arnaud Girault\n\nConfiguration\n# assets global configuration\nassets:\n images:\n optimize: true\n responsive:\n widths: [768, 1024]\n# configuration of images in Markdown\npages:\n body:\n images:\n formats: [avif, webp]\n responsive: true\n lazy: true\n decoding: true\n placeholder: color\nGenerated HTML\n<picture>\n <source\n type=\"image\/avif\"\n srcset=\"\/thumbnails\/1024\/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.avif 1024w,\n \/thumbnails\/768\/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.avif 768w\"\n sizes=\"100vw\"\n width=\"1024\"\n height=\"681\"\n >\n <source\n type=\"image\/webp\"\n srcset=\"\/thumbnails\/1024\/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.webp 1024w,\n \/thumbnails\/768\/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.webp 768w\"\n sizes=\"100vw\"\n width=\"1024\"\n height=\"681\"\n >\n <img src=\"\/thumbnails\/1024\/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg\"\n alt=\"Photo by Arnaud Girault\"\n loading=\"lazy\"\n decoding=\"async\"\n width=\"1024\"\n height=\"681\"\n style=\";max-width:100%;height:auto;background-color:rgb(58, 56, 44);\"\n srcset=\"\/thumbnails\/1024\/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg 1024w,\n \/thumbnails\/768\/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg 768w\"\n sizes=\"100vw\"\n >\n<\/picture>", "content_html": "

One of the most effective ways to improve the performance of your website is to optimize images.

\n

Cecil can manage the following optimizations for images in Markdown, automatically:

\n
    \n
  1. Dimensions: Images dimensions are set to ensure proper layout and prevent layout shifts
    2. \n
  2. Compression: The image is compressed to reduce file size without significant loss of quality
    3. \n
  3. Image formats: Cecil generates AVIF and WebP formats for the image
    4. \n
  4. Responsive images: Cecil generates two different sizes of the image (based on the configuration) to serve the appropriate size for different devices
    5. \n
  5. Lazy loading: The image is set to load lazily, meaning it will only load when it comes into the viewport
    6. \n
  6. Decoding: The image is set to decode asynchronously, improving the initial page load time
    7. \n
  7. Placeholder: A color placeholder is used while the image is loading
    8. \n
\n\n

Example

\n

Bellow an example with a PNG image 1920x1276 pixels.

\n
![A star forming region in the sky](../../assets/arnaud-girault-IjEtFjxXweE-unsplash.jpg \"Photo by Arnaud Girault\"){placeholder=color}
\n
\n\n\n\n\"A\n\n
Photo by Arnaud Girault
\n
\n

Configuration

\n
# assets global configuration\nassets:\n  images:\n    optimize: true\n    responsive:\n      widths: [768, 1024]\n# configuration of images in Markdown\npages:\n  body:\n    images:\n      formats: [avif, webp]\n      responsive: true\n      lazy: true\n      decoding: true\n      placeholder: color
\n

Generated HTML

\n
<picture>\n  <source\n    type=\"image/avif\"\n    srcset=\"/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.avif 1024w,\n            /thumbnails/768/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.avif 768w\"\n    sizes=\"100vw\"\n    width=\"1024\"\n    height=\"681\"\n  >\n  <source\n    type=\"image/webp\"\n    srcset=\"/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.webp 1024w,\n            /thumbnails/768/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.webp 768w\"\n    sizes=\"100vw\"\n    width=\"1024\"\n    height=\"681\"\n  >\n  <img src=\"/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg\"\n    alt=\"Photo by Arnaud Girault\"\n    loading=\"lazy\"\n    decoding=\"async\"\n    width=\"1024\"\n    height=\"681\"\n    style=\";max-width:100%;height:auto;background-color:rgb(58, 56, 44);\"\n    srcset=\"/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg 1024w,\n            /thumbnails/768/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg 768w\"\n    sizes=\"100vw\"\n  >\n</picture>
", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/templates-image-formats/", "url": "https://cecil-945.pages.dev/how-to/templates-image-formats/", "title": "Generate multiple formats of an image in templates", "summary": "Generate AVIF and WebP image formats in Cecil templates.", "date_published": "2025-06-01T00:00:00+00:00","content_text": "For performance and bandwidth optimization, Cecil can generate multiple formats of an image, such as AVIF and WebP. This allows the browser to select the best format based on its capabilities:\n{{ html(asset('image.jpg'), attributes={alt: 'Alternative description'}, options={formats: ['avif', 'webp']}) }}\n\nAVIF and WebP are image formats that have superior compression and quality characteristics compared to their older JPEG and PNG counterparts. Encoding your images in these formats rather than JPEG or PNG means that they will load faster and consume less cellular data.\nAVIF is supported in Chrome, Firefox, and Opera and offers smaller file sizes compared to other formats with the same quality settings.\nWebP is supported in the latest versions of Chrome, Firefox, Safari, Edge, and Opera and provides better lossy and lossless compression for images on the web.\n\n– Chrome Lighthouse docs\nExample\nBelow an example of how to generate AVIF and WebP formats of an image:\n{{ html(asset('cecil-logo.png'), attributes={alt: 'Cecil logo'}, options={formats: ['avif', 'webp']}) }}\nGenerated HTML\n<picture>\n <source type=\"image\/avif\" srcset=\"\/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.avif\">\n <source type=\"image\/webp\" srcset=\"\/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.webp\">\n <img src=\"\/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.png\" width=\"250\" height=\"250\" alt=\"Cecil logo\">\n<\/picture>", "content_html": "

For performance and bandwidth optimization, Cecil can generate multiple formats of an image, such as AVIF and WebP. This allows the browser to select the best format based on its capabilities:

\n
{{ html(asset('image.jpg'), attributes={alt: 'Alternative description'}, options={formats: ['avif', 'webp']}) }}
\n
\n

AVIF and WebP are image formats that have superior compression and quality characteristics compared to their older JPEG and PNG counterparts. Encoding your images in these formats rather than JPEG or PNG means that they will load faster and consume less cellular data.

\n

AVIF is supported in Chrome, Firefox, and Opera and offers smaller file sizes compared to other formats with the same quality settings.

\n

WebP is supported in the latest versions of Chrome, Firefox, Safari, Edge, and Opera and provides better lossy and lossless compression for images on the web.

\n
\n

– Chrome Lighthouse docs

\n

Example

\n

Below an example of how to generate AVIF and WebP formats of an image:

\n
{{ html(asset('cecil-logo.png'), attributes={alt: 'Cecil logo'}, options={formats: ['avif', 'webp']}) }}
\n

Generated HTML

\n
<picture>\n  <source type=\"image/avif\" srcset=\"/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.avif\">\n  <source type=\"image/webp\" srcset=\"/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.webp\">\n  <img src=\"/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.png\" width=\"250\" height=\"250\" alt=\"Cecil logo\">\n</picture>
", "language": "en" }, { "id": "https://cecil-945.pages.dev/how-to/templates-responsive-images/", "url": "https://cecil-945.pages.dev/how-to/templates-responsive-images/", "title": "Render responsive images in templates", "summary": "Render responsive images in Cecil templates with the html function.", "date_published": "2024-01-18T00:00:00+00:00", "date_modified": "2025-05-12T00:00:00+00:00","content_text": "The easiest way to render responsive images in templates is with the html function:\n{{ html(asset('image.jpg'), attributes={alt: 'Alternative description'}, options={responsive: true}) }}\nThe default width values of the generated images are 480, 640, 768, 1024, 1366, 1600 and 1920. They can be modified in the assets section of the configuration.\nExample\nBelow an example with a PNG image 1000x1000 pixels.\n{{ html(asset('cecil-logo-1000.png'), attributes={alt: 'Cecil logo'}, options={responsive: true}) }}\nConfiguration\nassets:\n images:\n responsive:\n widths: [768, 1024]\nGenerated HTML\n<img\n alt=\"Cecil logo\"\n width=\"1000\"\n height=\"1000\"\n src=\"\/cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png\"\n srcset=\"\/thumbnails\/768\/cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png 768w,\n \/cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png 1000w\"\n sizes=\"100vw\"\n>", "content_html": "

The easiest way to render responsive images in templates is with the html function:

\n
{{ html(asset('image.jpg'), attributes={alt: 'Alternative description'}, options={responsive: true}) }}
\n\n

Example

\n

Below an example with a PNG image 1000x1000 pixels.

\n
{{ html(asset('cecil-logo-1000.png'), attributes={alt: 'Cecil logo'}, options={responsive: true}) }}
\n

Configuration

\n
assets:\n  images:\n    responsive:\n      widths: [768, 1024]
\n

Generated HTML

\n
<img\n  alt=\"Cecil logo\"\n  width=\"1000\"\n  height=\"1000\"\n  src=\"/cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png\"\n  srcset=\"/thumbnails/768/cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png 768w,\n          /cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png 1000w\"\n  sizes=\"100vw\"\n>
", "language": "en" } ] }