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’unemap, avec la même syntaxe que les variables d’une page (raccourci de type ou ensemble de règles,fieldsetitemscompris). 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èglesenumetpatternde 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 (
minetmaxde 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 avecitems: mixed, et les règlesrequiredetdefaultne s’appliquent pas aux éléments. - Les règles
minetmaxd’une liste s’appliquent à son nombre d’éléments. - Une
mapavecfieldsn’accepte pas les règlesmin,max,enumetpattern(sansfields,minetmaxs’appliquent à son nombre de variables). - La valeur
defaultd’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.ymlest le schéma de la pageblog/billet-1). - Le schéma de toutes les pages (
*) est le fichier_all.yml. - Une clé ne peut pas avoir deux fichiers (
blog.ymletblog.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é :
- dossiers
schemasdes thèmes (un thème surcharge les thèmes qui le suivent dans la liste) ; pages.schemaduconfig.ymldes thèmes (un thème surcharge les thèmes qui le suivent dans la liste) ;- dossier
schemasdu site ; pages.schemade 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 CSShljs-*)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 CSShl-*)
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)
pages.body.links
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 :
- désactivée :
published: false - exclue des pages de liste :
excluded: true - 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