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