Insert a table of contents

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

[toc]

## Installation
### Requirements
## Usage

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

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

Display the table of contents in a template

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

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

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

Add notes

Highlight information with a note block:

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

Is converted to:

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

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

Add attributes

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:

## Installation {#install .highlighted}

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

Redirect old URLs to a page

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

---
title: About
alias:
  - contact
  - about-us
---

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

Redirect a page to another URL

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

---
title: Old documentation
redirect: "https://cecil.app/documentation/"
---

Without a Markdown file

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

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

Generated pages

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

• a <link rel="canonical"> to the target URL
• a <meta name="robots" content="noindex"> tag, so search engines don’t index it
• a <meta http-equiv="refresh"> tag and a JavaScript redirection
• a fallback link for visitors

Keep production values in cecil.yml

title: "My site"
baseurl: https://example.com/
debug: false

Override with extra config files

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

baseurl: http://localhost:8000/
debug: true

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

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

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

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

Override with environment variables

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):

export CECIL_BASEURL="https://staging.example.com/"
export CECIL_DEBUG=true
php cecil.phar build

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

CECIL_BASEURL="http://localhost:8000/"
CECIL_DEBUG=true

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

# .gitlab-ci.yml
pages:
  variables:
    CECIL_ENV: production
    CECIL_OUTPUT_DIR: public

Read the environment in templates

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

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

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

{% if site.debug %}{{ dump(page) }}{% endif %}

Configure assets processing

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

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

Load a stylesheet

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

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

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

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

Bundle JavaScript files

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

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

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

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

Add Subresource Integrity

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

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

Inline critical CSS

Output the content of an asset with the inline filter:

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

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

<style>
{% apply scss_to_css|minify_css %}
  $color: #fcfcfc;
  body {
    background-color: $color;
  }
{% endapply %}
</style>

Declare vocabularies

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

taxonomies:
  categories: category
  tags: tag

Classify pages

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

---
title: My first post
categories: ["Development"]
tags: ["PHP", "Static site"]
---

Cecil generates:

• /tags/: the list of the terms of the vocabulary
• /tags/php/ and /tags/static-site/: the list of the pages of each term

Customize the list of terms

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

{% extends 'page.html.twig' %}

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

Customize the pages of a term

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

{% extends 'page.html.twig' %}

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

Display the terms of a page

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

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

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

Declare entries in configuration

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

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

Add a page from its front matter

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:

---
title: Our Expertise
menu:
  main:
    weight: 15
  footer:
    weight: 15
    name: "Expertise" # override the entry name in this menu
---

Override or disable an entry

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

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

Render the menu

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

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

A single entry can also be reached by its ID:

{% if site.menus.main.about is defined %}
  <a href="{{ url(site.menus.main.about.url) }}">{{ site.menus.main.about.name }}</a>
{% endif %}

Create the index page

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

pages/search.md

---
title: Search index
layout: search
output: json
excluded: true
---

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

Write the JSON template

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

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

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

Search with Fuse.js

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

<input type="search" id="search" placeholder="Search…">
<ul id="results"></ul>

<script type="module">
  import Fuse from 'https://cdn.jsdelivr.net/npm/fuse.js@7/dist/fuse.mjs';

  const index = await fetch('{{ url('search', {format: 'json'}) }}').then(r => r.json());
  const fuse = new Fuse(index, { keys: ['title', 'description', 'content'], threshold: 0.3 });
  const results = document.getElementById('results');

  document.getElementById('search').addEventListener('input', (e) => {
    results.replaceChildren(...fuse.search(e.target.value, { limit: 10 }).map(({ item }) => {
      const li = document.createElement('li');
      const a = document.createElement('a');
      a.href = item.url;
      a.textContent = item.title;
      li.append(a);
      return li;
    }));
  });
</script>

Alternative: Pagefind

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

php cecil.phar build
npx pagefind --site _site

Then load its UI in a template:

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>
<div id="search"></div>
<script>
  window.addEventListener('DOMContentLoaded', () => new PagefindUI({ element: '#search' }));
</script>

Enable GitHub Pages

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

Add the workflow

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

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

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.

Base URL

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.

Customize the build

The action accepts the following optional inputs:

      - name: Build site
        uses: Cecilapp/Cecil-Action@v4
        with:
          version: '9.6.2'       # Cecil version (latest by default)
          install_themes: 'no'   # skip themes installation (`yes` by default)
          options: '-v --drafts' # build command options (`-v` by default)

Enable feeds for all list pages

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

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

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).

Enable a feed for a single section

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

---
title: Blog
output: [html, rss]
---

Advertise the feed

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>.

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

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

Customize the feed template

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.

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

{% extends '_default/list.rss.twig' %}

{% block item %}
      <guid>{{ url(item, {canonical: true}) }}</guid>
      <title>{{ item.title|e }}</title>
      <pubDate>{{ item.date|date('r') }}</pubDate>
      <link>{{ url(item, {canonical: true}) }}</link>
      <description><![CDATA[{{ item.content|excerpt_html }}]]></description>
{% endblock %}

Configure pagination

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

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

Override it for a section

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

---
title: Blog
pagination:
  max: 20
---

Or disable it for this section only:

---
pagination: false
---

Display the paginated pages

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:

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

Add navigation links

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

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

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

{% if page.paginator %}
<nav>
  {% for i in 1..page.paginator.count %}
    {% if i == page.paginator.current %}
  <span aria-current="page">{{ i }}</span>
    {% elseif i == 1 %}
  <a href="{{ url(page.paginator.links.first) }}">{{ i }}</a>
    {% else %}
  <a href="{{ url(page.paginator.links.path ~ '/' ~ i) }}">{{ i }}</a>
    {% endif %}
  {% endfor %}
</nav>
{% endif %}

Declare languages

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

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

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

Translate a page

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

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

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

---
title: À propos
slug: a-propos
---

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

Link translated pages

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

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

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

Translate template strings

Wrap texts with the trans tag or filter:

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

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

# translations/messages.fr_FR.yaml
Read more: Lire la suite

Extract the strings of your templates with:

php cecil.phar util:translations:extract --locale=fr_FR --save

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

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

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

{{ include('partials/metatags.html.twig', {title: 'Custom title', image: og_image}) }}

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

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

Example

Bellow an example with a PNG image 1920x1276 pixels.

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

Configuration

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

Generated HTML

<picture>
  <source
    type="image/avif"
    srcset="/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.avif 1024w,
            /thumbnails/768/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.avif 768w"
    sizes="100vw"
    width="1024"
    height="681"
  >
  <source
    type="image/webp"
    srcset="/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.webp 1024w,
            /thumbnails/768/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.webp 768w"
    sizes="100vw"
    width="1024"
    height="681"
  >
  <img src="/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg"
    alt="Photo by Arnaud Girault"
    loading="lazy"
    decoding="async"
    width="1024"
    height="681"
    style=";max-width:100%;height:auto;background-color:rgb(58, 56, 44);"
    srcset="/thumbnails/1024/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg 1024w,
            /thumbnails/768/arnaud-girault-IjEtFjxXweE-unsplash.c0bdd31264ac3d0d364d02bced31038f.jpg 768w"
    sizes="100vw"
  >
</picture>

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

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.

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

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.

– Chrome Lighthouse docs

Example

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

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

Generated HTML

<picture>
  <source type="image/avif" srcset="/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.avif">
  <source type="image/webp" srcset="/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.webp">
  <img src="/cecil-logo.c1af8a129a0cde81f9b94ffbf452e10b.png" width="250" height="250" alt="Cecil logo">
</picture>

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

Example

Below an example with a PNG image 1000x1000 pixels.

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

Configuration

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

Generated HTML

<img
  alt="Cecil logo"
  width="1000"
  height="1000"
  src="/cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png"
  srcset="/thumbnails/768/cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png 768w,
          /cecil-logo-1000.fbacb922cddbcdb7ca9a03a3ca3cf2ca.png 1000w"
  sizes="100vw"
>