Front matter YAML : les métadonnées en tête d'un fichier Markdown
Front matter YAML
Front matter YAML en Markdown : syntaxe, champs et exemples | We.Inc
Ce qu'est le front matter YAML, les règles du ---, les champs que lisent Jekyll, Hugo, Eleventy et Astro, et un séparateur qui affiche les métadonnées et le contenu de votre propre fichier.
Le front matter est un bloc YAML placé tout en haut d'un fichier Markdown, ouvert et fermé par une ligne de trois tirets (---). Les générateurs de sites statiques le lisent comme les données de la page, par exemple le titre, la date, le layout et les tags, puis affichent tout ce qui se trouve sous la ligne de fermeture comme contenu de la page.
La prise en charge du front matter dans quatre générateurs de sites statiques populaires
Générateur
Formats
Champs qu'il lit lui-même
Jekyll
YAML entre ---
layout, permalink, published ; pour les articles : date, category, categories, tags
Le front matter transforme un simple fichier Markdown en page dotée de métadonnées, et un seul tiret mal placé suffit à le casser. Collez un fichier dans le séparateur pour voir exactement où s'arrêtent les métadonnées et où commence le contenu, et quels champs de premier niveau il a trouvés, avant que votre build ne s'en plaigne.
Collez un fichier Markdown, ou modifiez l'article d'exemple.
Le séparateur vérifie que la toute première ligne est --- (YAML) ou +++ (TOML) et cherche la ligne de fermeture correspondante.
Il affiche le bloc de front matter, les champs simples de premier niveau qu'il a trouvés et le contenu qui sera rendu.
Si le bloc n'est jamais fermé, il vous le signale : c'est la cause la plus courante d'une page qui affiche ses métadonnées sous forme de texte.
Rien ne doit précéder le --- d'ouverture, pas même une ligne vide ou un BOM (indicateur d'ordre des octets), sinon la plupart des générateurs traitent le bloc comme du texte ordinaire.
Mettez entre guillemets les titres qui contiennent deux-points suivis d'un espace, comme "Pricing: what changed", sinon YAML les lit comme un mapping imbriqué.
Écrivez les dates au format YYYY-MM-DD pour que les générateurs et les librairies YAML s'accordent sur leur sens.
Regroupez vos champs personnalisés dans un emplacement cohérent. Hugo, par exemple, dispose d'une clé params prévue pour vos propres valeurs.
Questions fréquentes
Qu'est-ce que le front matter en Markdown ?
Ce sont des métadonnées écrites en haut d'un fichier Markdown entre deux lignes délimitatrices. Markdown lui-même ne le définit pas ; les générateurs de sites statiques et les outils de contenu ont adopté cette convention et le lisent comme des données avant de rendre le reste.
Le front matter doit-il être en YAML ?
YAML est le choix par défaut le plus courant, mais pas le seul. Hugo accepte le TOML entre des lignes +++ et le JSON entre accolades, Eleventy prend en charge ---json et ---js, et Astro accepte aussi le TOML.
Pourquoi ma page affiche-t-elle le front matter sous forme de texte ?
En général, quelque chose se trouve avant le premier ---, le --- de fermeture manque, ou la ligne d'ouverture contient des caractères en trop. Le séparateur ci-dessus signale immédiatement les deux derniers cas.
Le front matter peut-il être vide ?
Oui. Dans Jekyll, une paire de lignes --- vide marque quand même le fichier pour traitement : c'est ainsi que des fichiers CSS ou de flux voient leurs balises Liquid rendues sans aucune métadonnée.
Comment lire le front matter dans mon propre code ?
Découpez le fichier aux délimiteurs, analysez la première partie avec une librairie YAML et passez le reste à votre moteur de rendu Markdown. Eleventy le fait avec le paquet gray-matter, que vous pouvez aussi utiliser directement dans Node.
Les règles des délimiteurs
La documentation de Jekyll est claire : le front matter doit être la première chose du fichier et doit être du YAML valide placé entre des lignes de trois tirets. Les autres générateurs suivent la même forme.
À l'intérieur du bloc, le YAML normal s'applique. Indentez avec des espaces, mettez entre guillemets les valeurs contenant des caractères spéciaux et utilisez des listes pour les tags et les catégories.
Les champs à définir sur chaque page
Un titre et une description couvrent l'en-tête de la page et l'extrait dans les résultats de recherche dans la plupart des thèmes. Une date ordonne les articles, et draft ou published décide si la page est générée ou non.
Tout le reste dépend de vos templates. Chaque champ ajouté devient une donnée que le layout peut afficher, comme un nom d'auteur, le chemin d'une image principale ou un temps de lecture.
Exemples de front matter
Un article de blog (YAML)
Un article typique : titre entre guillemets car il contient deux-points, une date, une liste de tags et un champ author personnalisé.
Le même article avec un front matter TOML (Hugo)
Hugo lit +++ comme un front matter TOML. Les valeurs personnalisées se placent sous la clé params.
Séparateur de front matter
Collez un fichier Markdown. Le séparateur trouve le bloc de front matter, liste ses champs simples de premier niveau et affiche le contenu qui sera rendu.
Fichier Markdown
Front matter ({f})
Champs de premier niveau trouvés
Aucune ligne simple clé: valeur au premier niveau.
Contenu
Pas de front matter : la première ligne n'est ni --- ni +++, donc tout le fichier est traité comme du contenu.
Le bloc ouvert par {d} n'est jamais fermé. Ajoutez une ligne {d} correspondante après le dernier champ.