Accueil › Blog › Front matter YAML et aide-mémoire Markdown
Vous utilisez Jekyll, Hugo ou Astro et vos fichiers .md commencent par un bloc --- de métadonnées ? Ou vous cherchez simplement à retrouver rapidement une syntaxe Markdown que vous utilisez rarement, sans quitter votre éditeur ? Ce guide traite ces deux cas concrets — et où un aperçu Markdown classique s'arrête aujourd'hui.
--- en tête de fichier — n'appartient pas à la syntaxe Markdown de base : un moteur d'aperçu générique le traite comme du texte ou comme une ligne horizontale suivie de texte brut, sauf s'il a été spécifiquement conçu pour le reconnaître.Les générateurs de site statique comme Jekyll, Hugo ou Astro utilisent une convention répandue : les premières lignes du fichier, encadrées par deux ---, contiennent des paires clé/valeur (title:, date:, tags:, layout:...) qui pilotent la génération de la page, avant même le contenu Markdown proprement dit. Le problème, c'est que trois tirets seuls sur une ligne sont aussi la syntaxe standard d'une ligne horizontale (<hr>) en Markdown. Un aperçu qui ne fait pas de distinction entre les deux cas rendra donc le premier bloc --- comme une ligne horizontale, suivie du texte YAML brut affiché tel quel — clés, deux-points et valeurs compris — plutôt que comme un panneau de métadonnées séparé du contenu.
Concrètement, si vous collez un fichier commençant ainsi dans un aperçu Markdown qui ne détecte pas le front matter :
| Contenu du fichier .md (exemple hypothétique) | Rendu attendu si le front matter est détecté |
|---|---|
--- | Bloc de métadonnées affiché à part (ou masqué), séparé visuellement du corps |
# Introduction | Titre de niveau 1, comme d'habitude |
Le corps du document (à partir du #) se rend normalement dans la plupart des outils actuels, y compris ceux qui ne reconnaissent pas le front matter — c'est uniquement le bloc de tête qui pose problème visuellement.
--- ... --- avant de coller le fichier dans l'aperçu, puis de ne vérifier que le corps du contenu.C'est une manipulation de quelques secondes : sélectionnez les lignes entre les deux séparateurs (métadonnées incluses) et supprimez-les avant de coller le reste dans l'éditeur. Vous perdez la vérification visuelle des métadonnées elles-mêmes — ce qui est rarement un problème puisque title: ou date: n'ont de toute façon pas de « rendu » HTML à proprement parler, elles servent au moteur de génération du site, pas à l'affichage.
--- en toute première ligne du fichier délimite des métadonnées plutôt qu'une ligne horizontale, puis l'afficher séparément du corps — est une fonctionnalité qui pourrait s'ajouter à un aperçu Markdown à l'avenir. Ce n'est pas le cas de tous les outils en ligne aujourd'hui, d'où l'intérêt de connaître ce contournement manuel en attendant.Même les personnes qui écrivent du Markdown régulièrement oublient parfois la syntaxe des éléments les moins fréquents : comment centrer une colonne dans un tableau (un deux-points de chaque côté des tirets de séparation), comment imbriquer une case à cocher sous une autre, ou comment échapper un caractère spécial comme un astérisque littéral. Aujourd'hui, la réponse la plus rapide est souvent une recherche externe. Un panneau d'aide-mémoire intégré directement à la barre d'outils de l'éditeur — qui rappellerait ces cas en un coup d'œil, sans changer de page — réduirait ces interruptions, en particulier pour les personnes qui rédigent occasionnellement en Markdown plutôt que quotidiennement.
En pratique, la combinaison des deux approches — un aperçu HTML en direct pour valider le résultat, et un aide-mémoire pour se rappeler la syntaxe à taper — couvre les deux moments distincts de l'écriture Markdown : avant de taper (« comment fait-on ça ? ») et après avoir tapé (« est-ce que ça rend bien ? »).
Collez votre Markdown, importez un fichier .md, ou partez d'un modèle prêt à l'emploi — l'aperçu HTML se met à jour en direct, entièrement dans votre navigateur.
Essayer l'outil →---) au début et à la fin. Il contient des paires clé/valeur comme title, date ou tags, utilisées par des générateurs de site statique (Jekyll, Hugo, Astro) pour organiser le contenu — ce n'est pas du Markdown au sens strict, donc un aperçu qui ne le reconnaît pas l'affichera comme du texte brut ou une ligne horizontale suivie de texte.--- au tout début d'un fichier est ambiguë : en Markdown standard, trois tirets seuls sur une ligne créent une ligne horizontale, pas un bloc de métadonnées. Un moteur d'aperçu qui ne détecte pas explicitement le front matter YAML rendra donc le contenu entre les deux --- comme du texte normal, avec les deux-points et tirets visibles tels quels.--- de tête, supprimez-le temporairement avant de coller le contenu, puis vérifiez uniquement le corps du document. Vous éviterez ainsi que les clés YAML brutes polluent visuellement le rendu HTML.