Logo de Cecil Cecil
Sur cette page

Pages

Ces options contrôlent la façon dont les pages sont chargées, triées, paginées, routées et générées.

pages.dir

Répertoire source des pages (pages par défaut).

pages:
  dir: pages

pages.ext

Extensions des fichiers de pages.

pages:
  ext: [md, markdown, mdown, mkdn, mkd, text, txt]

pages.exclude

Répertoires, chemins et noms de fichiers à exclure (accepte les globs, les chaînes et les expressions régulières).

pages:
  exclude: ['vendor', 'node_modules', '*.scss', '/\.bck$/']

pages.prefix.separator

Liste des caractères utilisés comme séparateur entre un préfixe de nom de fichier (date ou weight) et le slug.

pages:
  prefix:
    separator: ['-', '_']

pages.sortby

Méthode de tri par défaut des collections.

pages:
  sortby: date # `date`, `updated`, `title` ou `weight`
  # ou
  sortby:
    variable: date    # `date`, `updated`, `title` ou `weight`
    desc_title: false # tri par titre décroissant
    reverse: false    # inverse l’ordre de tri

pages.pagination

La pagination est disponible pour les pages de liste (type homepage, section ou term).

pages:
  pagination:
    max: 5     # nombre maximum d’entrées par page
    path: page # chemin de la page paginée

Désactiver la pagination

La pagination peut être désactivée :

pages:
  pagination: false

Ou :

pages:
  pagination:
    enabled: false

pages.paths

Applique un path personnalisé à toutes les pages d’une section.

pages:
  paths:
    - section: <section’s ID>
      path: <path of pages>

Variables de chemin

  • :year
  • :month
  • :day
  • :section
  • :slug

Exemple :

pages:
  paths:
    - section: Blog
      path: :section/:year/:month/:day/:slug # ex. : /blog/2020/12/01/my-post/
# localized
languages:
  - code: fr
    name: Français
    locale: fr_FR
    config:
      pages:
        paths:
          - section: Blog
            path: blogue/:year/:month/:day/:slug # ex. : /blogue/2020/12/01/mon-billet/

pages.frontmatter

Format du front matter des pages (yaml par défaut, accepte aussi ini, toml et json).

pages:
  frontmatter: yaml

pages.validation

Comportement lorsque le front matter d’une page ne respecte pas son schéma :

  • warning : journalise un avertissement et conserve la page ;
  • error (par défaut) : journalise une erreur et ignore la page ;
  • strict : le build échoue ;
  • false : désactive la validation.
pages:
  validation: error

pages.schema

Schémas du front matter, par Section ou par page (* s’applique à toutes les pages).

Les schémas peuvent aussi être écrits dans le dossier schemas, un fichier par Section ou par page.

Chaque variable est définie par son type, ou par un ensemble de règles :

Règle Description
type string, int, number, bool, date, list, map, scalar ou mixed (par défaut).
required La variable doit être définie (false par défaut).
enum Liste des valeurs autorisées.
pattern Expression régulière que la valeur doit respecter (string et scalar).
min Valeur (int, number), longueur (string) ou nombre d’éléments (list, map) minimum.
max Valeur (int, number), longueur (string) ou nombre d’éléments (list, map) maximum.
items Type ou définition des éléments d’une list (voir listes et maps).
fields Définitions des variables d’une map (voir listes et maps).
default Valeur appliquée lorsque la variable n’est pas définie.
format Ce que contient une string : text, markdown, url, email ou path (voir description des variables).
label Nom de la variable, pour les outils qui éditent le front matter.
description Texte d’aide de la variable, pour les outils qui éditent le front matter.
pages:
  schema:
    '*':
      title:
        type: string
        required: true
    blog:
      author: string # raccourci de type
      rating:
        type: int
        min: 1
        max: 5
      category:
        type: string
        enum: [news, tutorial]
        default: news
      tags:
        type: list
        items: string
        max: 5

La longueur d’une chaîne (règles min et max) est comptée en caractères, et non en octets.

Listes et maps

La structure d’une map et des éléments d’une list peut être validée, à toute profondeur :

  • fields : définitions des variables d’une map, avec la même syntaxe que les variables d’une page (raccourci de type ou ensemble de règles, fields et items compris). Comme une page, une map est ouverte : les variables non déclarées sont autorisées.
  • items : le type des éléments (items: string), ou la définition des éléments (items: {type: map, fields: …}).

Portée des règles :

  • Avec un type d’éléments (items: string), les règles enum et pattern de la liste s’appliquent à ses éléments.
  • Avec une définition d’éléments, seules les règles de cette définition s’appliquent aux éléments (min et max de la définition s’appliquent à chaque élément : longueur d’une chaîne, valeur d’un nombre, etc.). Un élément ne peut pas être vide (null), sauf avec items: mixed, et les règles required et default ne s’appliquent pas aux éléments.
  • Les règles min et max d’une liste s’appliquent à son nombre d’éléments.
  • Une map avec fields n’accepte pas les règles min, max, enum et pattern (sans fields, min et max s’appliquent à son nombre de variables).
  • La valeur default d’une variable d’une map est appliquée lorsque la map est définie mais pas la variable (une map absente n’est pas créée), y compris dans chaque élément d’une liste.

Exemple : chaque image d’une illustration doit avoir un nom de fichier et un texte alternatif d’au moins 20 caractères.

pages:
  schema:
    illustrations:
      description: {type: string, required: true}
      images:
        type: list
        min: 1
        items:
          type: map
          fields:
            file: {type: string, required: true, pattern: '^[\w-]+\.(png|jpe?g|gif|webp)$'}
            alt: {type: string, required: true, min: 20}

Une erreur donne le chemin de la variable invalide, à partir de 0 pour le premier élément d’une liste : The mandatory variable 'images › 1 › alt' is missing. (texte alternatif de la deuxième image).

Schéma d’une page

Une clé de pages.schema peut aussi être une page, pour les pages qui ont leurs propres variables (une page d’accueil, un CV, etc.). La clé est l’identifiant de la page, sans sa langue : le chemin de son fichier dans le dossier des pages, sans préfixe, langue ni extension.

Fichier Clé
index.md index
cv.md, cv.en.md cv
1-Mon projet.md mon-projet
blog/2024-05-01_post.md blog/post
blog/index.md blog/index

Les variables sont celles de *, puis de la section de la page, puis de la page : les dernières surchargent les autres.

pages:
  schema:
    blog:        # pages de la section « blog »
      author: {type: string, required: true}
    blog/index:  # index de la section « blog »
      intro: string
    cv:          # page « cv.md », et ses traductions
      skills:
        type: list
        items:
          type: map
          fields:
            name: {type: string, required: true}
            level: {type: int, min: 0, max: 100}

Description des variables

Les règles format, label et description décrivent une variable aux outils qui éditent le front matter (par exemple, Cecil Desktop construit son formulaire à partir du schéma). Elles sont acceptées sur toute variable, y compris dans fields et items.

format indique ce que contient une string :

Format Description
text Texte de plusieurs lignes.
markdown Texte de plusieurs lignes, rendu en Markdown par le template.
url URL absolue (https://cecil.app) : validée.
email Adresse e-mail : validée.
path Chemin d’un fichier du site (asset ou fichier statique) : non contrôlé.
pages:
  schema:
    cv:
      intro:
        type: string
        format: markdown
        label: Introduction
        description: Affichée sous le titre de la page.
      website: {type: string, format: url}
      photo: {type: string, format: path, label: Photo}

label et description n’ont aucun effet sur la validation, pas plus que les formats text, markdown et path.

Répertoire des schémas

Plutôt que dans la configuration, les schémas peuvent être écrits dans le dossier schemas, à la racine du site : un fichier YAML (.yml ou .yaml) par clé de pages.schema, chargé automatiquement.

<monsiteweb>
├─ pages
└─ schemas
   ├─ _all.yml        <- '*' : toutes les pages
   ├─ blog.yml        <- section « blog »
   ├─ cv.yml          <- page « cv.md »
   ├─ index.yml       <- page d’accueil
   └─ blog
      └─ index.yml    <- page « blog/index.md » (clé « blog/index »)
  • Le chemin d’un fichier dans le dossier, sans son extension, est la clé du schéma : une Section, ou une page (schemas/blog/billet-1.yml est le schéma de la page blog/billet-1).
  • Le schéma de toutes les pages (*) est le fichier _all.yml.
  • Une clé ne peut pas avoir deux fichiers (blog.yml et blog.yaml) : c’est une erreur.
  • Un fichier contient directement les variables, comme sous pages.schema.<clé>, et un fichier vide est un schéma vide.
# schemas/cv.yml
sections:
  label: Sections
  type: list
  items:
    type: map
    fields:
      title: {type: string, required: true}
      text: {type: string, format: markdown}

équivaut à :

pages:
  schema:
    cv:
      sections:
        # …

Chaque fichier est validé au chargement de la configuration : une erreur donne le nom du fichier et le chemin de la variable invalide dans ce fichier (ex. Invalid schema file "schemas/cv.yml"). Comme dans pages.schema, un fichier dont la clé ne correspond à aucune Section ni à aucune page est ignoré.

Un thème peut aussi avoir un dossier schemas, pour les variables attendues par ses templates. Les schémas sont fusionnés de la plus faible à la plus forte priorité :

  1. dossiers schemas des thèmes (un thème surcharge les thèmes qui le suivent dans la liste) ;
  2. pages.schema du config.yml des thèmes (un thème surcharge les thèmes qui le suivent dans la liste) ;
  3. dossier schemas du site ;
  4. pages.schema de la configuration du site.

Pour une même clé, les variables sont fusionnées une à une, à chaque niveau et entre thèmes : la définition d’une variable remplace entièrement sa définition précédente (ses règles ne sont pas fusionnées et les listes enum ne sont pas cumulées), les autres variables sont conservées.

# schemas/blog.yml
author: {type: string, required: true}
tags: {type: list, items: string}
# cecil.yml
pages:
  schema:
    blog:
      author: string # « author » devient facultatif, « tags » est conservé

pages.converter

Classe utilisée pour convertir le front matter et le corps Markdown des pages (Cecil\Converter\Converter par défaut).

pages:
  converter: Cecil\Converter\Converter

Voir Convertisseur Markdown pour utiliser le vôtre.

pages.body

Options du corps des pages.

pages.body.parser

Classe de l’analyseur Markdown (Cecil\Converter\Parsedown par défaut). Elle doit hériter de Cecil\Converter\Parsedown : voir Analyseur Markdown pour ajouter votre propre syntaxe.

pages:
  body:
    parser: Cecil\Converter\Parsedown

pages.body.toc

En-têtes utilisés pour construire la table des matières ([h2, h3] par défaut).

pages:
  body:
    toc: [h2, h3]

pages.body.anchors

Titres avec un lien d’ancre ([h2, h3] par défaut) : un élément <a class="heading-anchor" href="#<id>"> vide est ajouté à la fin de chacun de ces titres ayant un ID, pour être stylé par les templates (ex. : un # affiché au survol).

pages:
  body:
    anchors: [h2, h3] # false pour désactiver les ancres

pages.body.highlight

Active la coloration syntaxique du code (true par défaut).

pages:
  body:
    highlight: false # `false` pour désactiver la coloration syntaxique

Le moteur de coloration peut être changé avec l’option engine :

pages:
  body:
    highlight:
      enabled: true    # `true` par défaut
      engine: tempest  # `highlightjs` (par défaut) ou `tempest`
  • highlightjs : highlight.php, un portage PHP de highlight.js (plus de 190 langages, classes CSS hljs-*)
  • tempest : tempest/highlight, un moteur de coloration rapide côté serveur (langages du web : PHP, HTML, CSS, JavaScript, JSON, YAML, Twig, SQL, XML, etc., classes CSS hl-*)

pages.body.images

Options de gestion des images.

pages:
  body:
    images:
      formats: []       # ajoute des formats d’image alternatifs comme `source` (ex. `[avif, webp]`, tableau vide par défaut)
      resize: 0         # redimensionne toutes les images à <width> (en pixels, `0` pour désactiver)
      responsive: false # ajoute des variantes responsives à l’attribut `srcset` (`false` par défaut)
      lazy: true        # ajoute l’attribut `loading="lazy"` (`true` par défaut)
      decoding: true    # ajoute l’attribut `decoding="async"` (`true` par défaut)
      caption: false    # place l’image dans un élément <figure> et ajoute une <figcaption> contenant le titre (`false` par défaut)
      placeholder: ''   # remplit l’arrière-plan de <img> avant le chargement ('color' ou 'lqip', vide par défaut)
      class: ''         # définit une classe par défaut sur chaque image (vide par défaut)
      dark_suffix: ~    # suffixe de l’image variante sombre (ex. `.dark`), désactivé par défaut
      mobile_suffix: ~  # suffixe de l’image variante mobile (ex. `.mobile`), désactivé par défaut
      mobile_media_query: '(max-width: 767px)' # media query de la `<source>` de la variante mobile
      remote:           # traitement des images distantes (mettre à `false` pour désactiver)
        fallback:         # chemin de l’image de secours, stockée dans le répertoire assets (vide par défaut)

Options de gestion des liens.

pages:
  body:
    links:
      embed:
        enabled: false     # transforme les liens en contenu embarqué si possible (`false` par défaut)
        video: [mp4, webm] # extensions des fichiers vidéo
        audio: [mp3, ogg, wav] # extensions des fichiers audio
      external:
        blank: false     # si `true`, ouvre le lien externe dans un nouvel onglet
        noopener: true   # si `true`, ajoute `noopener` à l’attribut `rel`
        noreferrer: true # si `true`, ajoute `noreferrer` à l’attribut `rel`
        nofollow: false  # si `true`, ajoute `nofollow` à l’attribut `rel`

pages.body.excerpt

Options de gestion des extraits.

pages:
  body:
    excerpt:
      separator: excerpt|break # chaîne utilisée comme séparateur (`excerpt|break` par défaut)
      capture: before          # partie à capturer, `before` ou `after` le séparateur (`before` par défaut)

pages.default

Les pages par défaut sont des pages sans fichier de contenu (front matter uniquement), indexées par ID, chacune avec un path et quelques variables de front matter.

Cecil fournit des pages par défaut intégrées (à partir de templates intégrés) :

pages:
  default:
    index:
      path: ''
      title: Home
      published: true
    404:
      path: 404
      title: Page not found
      layout: 404
      uglyurl: true
      published: true
      excluded: true
    robots:
      path: robots
      title: Robots.txt
      layout: robots
      output: txt
      published: true
      excluded: true
      multilingual: false
    sitemap:
      path: sitemap
      title: XML sitemap
      layout: sitemap
      output: xml
      changefreq: monthly
      priority: 0.5
      published: true
      excluded: true
      multilingual: false
    xsl/sitemap:
      path: xsl/sitemap
      layout: sitemap
      output: xsl
      uglyurl: true
      published: true
      excluded: true
    xsl/atom:
      path: xsl/atom
      layout: feed
      output: xsl
      uglyurl: true
      published: true
      excluded: true
    xsl/rss:
      path: xsl/rss
      layout: feed
      output: xsl
      uglyurl: true
      published: false
      excluded: true

Chaque page peut être :

  1. désactivée : published: false
  2. exclue des pages de liste : excluded: true
  3. exclue de la localisation : multilingual: false

Vous pouvez aussi ajouter vos propres pages (un thème peut faire de même dans son config.yml) :

pages:
  default:
    code:
      path: code
      redirect: https://github.com/ArnaudLigny

Comme toute autre page, une page par défaut est listée (par exemple dans site.pages.showable, dans le sitemap, sur la page d’accueil) : utilisez excluded: true pour exclure des listes une page technique (index JSON, manifeste, etc.).

pages.generators

Cecil utilise les générateurs pour créer des pages supplémentaires (par ex. sitemap, flux, pagination, etc.) à partir de pages existantes, ou à partir d’autres sources comme le fichier de configuration ou des sources externes.

Les générateurs sont indexés par nom et exécutés par ordre croissant de priorité. Voici la liste des générateurs fournis par Cecil :

pages:
  generators:
    DefaultPages: { class: Cecil\Generator\DefaultPages, priority: 10 }
    ExternalBody: { class: Cecil\Generator\ExternalBody, priority: 30 }
    Section:      { class: Cecil\Generator\Section, priority: 40 }
    Taxonomy:     { class: Cecil\Generator\Taxonomy, priority: 50 }
    Homepage:     { class: Cecil\Generator\Homepage, priority: 60 }
    Pagination:   { class: Cecil\Generator\Pagination, priority: 70 }
    Alias:        { class: Cecil\Generator\Alias, priority: 80 }
    Redirect:     { class: Cecil\Generator\Redirect, priority: 90 }

Un générateur intégré peut être désactivé ou déplacé par son nom :

pages:
  generators:
    Redirect: false            # désactivé
    Section: { priority: 45 }  # déplacé

Voir Extensions pour la syntaxe complète.

pages.subsets

Les sous-ensembles servent à générer une partie de la collection de pages, selon un chemin, une langue ou un format de sortie spécifique, avec la commande :

cecil build --render-subset=<name>
pages:
  subsets:
    <name>:
      path: <path> # chemin glob ou chaîne (ex. `blog/*`, `blog`)
      language: <language> # code de langue (ex. `en`, `fr`)
      output: <output> # format de sortie (ex. `html`, `atom`)

Exemple :

pages:
  subsets:
    blog_en:
      path: blog
      language: en
      output: html
    search_index:
      path: '*'
      output: json