Activer GitHub Pages

Dans votre dépôt, allez dans Settings → Pages puis, dans Build and deployment, choisissez GitHub Actions comme Source.

Ajouter le workflow

Créez le fichier .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

Le job build télécharge Cecil, installe les thèmes (si un fichier composer.json existe), génère le site et envoie le répertoire de sortie en tant qu’artefact Pages. Le job deploy le publie ensuite.

URL de base

Inutile de modifier baseurl dans cecil.yml : l’action génère le site avec l’URL fournie par GitHub Pages (par exemple https://<user>.github.io/<repository>/), via l’option --baseurl.

Personnaliser la génération

L’action accepte les paramètres optionnels suivants :

      - name: Build site
        uses: Cecilapp/Cecil-Action@v4
        with:
          version: '9.6.2'       # version de Cecil (la dernière par défaut)
          install_themes: 'no'   # ne pas installer les thèmes (`yes` par défaut)
          options: '-v --drafts' # options de la commande build (`-v` par défaut)

Activer les flux pour toutes les pages de liste

Définissez les formats appliqués à chaque type de page avec output.pagetypeformats :

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

Cecil génère alors rss.xml et feed.json à côté de chaque index.html de la page d’accueil et des sections (ex. /blog/rss.xml, /blog/feed.json).

Activer un flux pour une seule section

Pour publier un flux pour une seule section, utilisez la variable output dans le front matter de la page d’index de la section :

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

Signaler le flux

Si vos templates incluent le partial metatags, les balises <link rel="alternate"> pointant vers les flux de la page courante sont ajoutées automatiquement dans le <head>.

Sinon, ajoutez le lien vous-même avec la fonction url() et son option format :

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

Personnaliser le template du flux

Les flux sont générés par les templates intégrés _default/list.rss.twig, _default/list.atom.twig et _default/list.jsonfeed.twig. Selon les règles de recherche, créez layouts/list.rss.twig (toutes les pages de liste) ou layouts/blog/list.rss.twig (section blog uniquement) pour les surcharger.

Vous pouvez étendre le template intégré et redéfinir uniquement le bloc item, par exemple pour publier un extrait plutôt que le contenu complet :

{% 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 %}

Configurer la pagination

La pagination est activée par défaut pour les pages de liste (homepage, section et term), avec 5 entrées par page. Modifiez-la dans cecil.yml :

pages:
  pagination:
    max: 10    # nombre maximum d’entrées par page
    path: page # chemin des pages paginées

La surcharger pour une section

Définissez la variable pagination dans le front matter du fichier index de la section (ex. : pages/blog/index.md) :

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

Ou désactivez-la pour cette section uniquement :

---
pagination: false
---

Afficher les pages paginées

Dans le template de liste (ex. : layouts/blog/list.html.twig), bouclez sur page.paginator.pages et utilisez page.pages lorsque la pagination est désactivée :

{% 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 %}

Ajouter les liens de navigation

Les liens du paginator sont des identifiants de pages : utilisez la fonction url() pour créer des liens fonctionnels :

{% 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 %}

Pour lister tous les numéros de page, itérez de 1 à 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 %}

Déclarer les langues

Définissez la langue principale et la liste des langues disponibles dans 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"

Les options placées sous la clé config d’une langue remplacent les options globales (ici le title du site).

Traduire une page

Dupliquez la page de référence et suffixez son nom de fichier avec le code de la langue :

pages/
├─ about.md    # la page de référence
└─ about.fr.md # la version française

Utilisez la variable slug pour traduire l’URL de la page :

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

about.md est publiée sur /about/ et about.fr.md sur /fr/a-propos/.

Relier les pages traduites

Chaque page expose ses traductions via page.translations. Ajoutez un sélecteur de langue à votre template :

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

Vous pouvez aussi inclure le partial intégré : {{ include('partials/languages.html.twig') }}.

Traduire les textes des templates

Encadrez les textes avec le tag ou le filtre trans :

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

Ajoutez ensuite un fichier de traduction nommé d’après la locale de la langue dans le dossier translations :

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

Extrayez les textes de vos templates avec :

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>

Le partial lit d’abord le front matter de la page, puis reprend les options du site si nécessaire. Consultez la documentation de configuration des metatags pour voir toutes les options disponibles.

Si vous devez surcharger le titre ou l’image, passez des valeurs directement au partial :

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

Cecil gère automatiquement les optimisations suivantes pour les images Markdown :

1. Dimensions : Les dimensions des images sont définies pour garantir une mise en page correcte et éviter les décalages.
2. Compression : L'image est compressée pour réduire la taille du fichier sans perte significative de qualité.
3. Formats d'image : Cecil génère les formats AVIF et WebP pour l'image.
4. Images responsives : Cecil génère deux tailles d'image différentes (selon la configuration) pour s'adapter à la taille des différents appareils.
5. Chargement différé : L'image est configurée pour se charger de manière différée, c'est-à-dire uniquement lorsqu'elle apparaît dans la fenêtre d'affichage.
6. Décodage : Le décodage de l'image est configuré pour être asynchrone, ce qui améliore le temps de chargement initial de la page.
7. Espace réservé : Un espace réservé de couleur est utilisé pendant le chargement de l'image.

Exemple

Ci-dessous un exemple avec une image PNG 1920x1276 pixels.

![Une région de formation d’étoiles dans le ciel](../../assets/arnaud-girault-IjEtFjxXweE-unsplash.jpg "Photo de Arnaud Girault"){placeholder=color}

Configuration

# configuration globale des assets
assets:
  images:
    optimize: true
    responsive:
      widths: [768, 1024]
# configuration des images dans du Markdown
pages:
  body:
    images:
      formats: [avif, webp]
      responsive: true
      lazy: true
      decoding: true
      placeholder: color

HTML généré

<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 de 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: 'Description alternative'}, options={formats: ['avif', 'webp']}) }}

AVIF et WebP sont des formats d'image offrant des caractéristiques de compression et de qualité supérieures à leurs homologues JPEG et PNG plus anciens. Encoder vos images dans ces formats plutôt que JPEG ou PNG permet un chargement plus rapide et une consommation de données mobiles réduite.

AVIF est pris en charge par Chrome, Firefox et Opera et offre des tailles de fichier plus petites que d'autres formats à qualité égale.

WebP est pris en charge par les dernières versions de Chrome, Firefox, Safari, Edge et Opera et offre une meilleure compression avec et sans perte pour les images sur le Web.

– Documentation Chrome Lighthouse

Exemple

Ci-dessous un exemple de génération des formats AVIF et WebP d'une image :

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

HTML généré

<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: 'Description alternative'}, options={responsive: true}) }}

Exemple

Ci-dessous un exemple avec une image PNG 1000x1000 pixels.

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

Configuration

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

HTML généré

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