L’en-tête YAML
Pandoc prend en charge les en-têtes YAML[1] pour les fichiers Markdown.
L’en-tête YAML n’est pas indispensable pour produire un document mais elle permet de modifier les valeurs par défaut et d’améliorer la qualité du document (mise en page et métadonnées du document).
Il n’est pas indispensable de retenir tout ce que contient l’entête YAML. Le plus simple est de copier un modèle dans un fichier et de le réutiliser pour chaque projet.
L’en-tête YAML va sa placer au début du document Markdown (elle peut également se trouver dans un fichier à part) et est encadrée de trois tirets au début et à la fin.
Ci-dessous un exemple d’une en-tête YAML qui contient quelque instructions de mise en forme et les métadonnées du document produit (ici un pdf).
---
# format du document
documentclass: article
header-includes:
– \usepackage[french]{babel}
geometry:
– left=2.5cm
– right=2.5cm
– top=2.5cm
– bottom=2.5cm
– a4paper
linestretch: 1.5
fontsize: 11pt
toc: false
toc depth: 2
numbersections: false
# métadonnées
title: Titre du document
subtitle: Sous-titre du document
author: Non, Prénom
affiliation: ULiège
date: 2021 (cc-by)
abstract: Ce court document est destiné à démontrer …
keywords: Markdown, rédiger
subject: écriture numérique ouverte
Modified: 01/03/25 09:12:20
right: CC-BY 0.4
# liens
links-as-notes: true
linkcolor: green
urlcolor: blue
# bibliographie
bibliography: library.bib
csl: apa.csl
---Pour la rendre plus lisible, il est possible d’insérer (comme ci-dessus) des commentaires dans l’en-tête YAML.
À part pour le changement de langue, toutes les lignes de l’entête font directement référence à des variables que l’on modifie directement (variable: valeur). Pour la langue (qui par défaut est l’anglais), il faut utiliser une commande LaTeX : `\usepackage[french]{babel}. Cette commande va franciser la mise en forme (par exemple : “Table des matières” au lieu de “Contents” ou des tirets longs au lieu de bulets dans les listes). Il est possible d’ajouter de nombreuses options dans header-includes (contenu de l’entête LaTeX) via des packages (voir “Troisième partie”).
Format du document
documentclass:avec book ou report ou article (et également chapter ou part). La mise en forme finale va varier en fonction de la classe.
geometry:va formater la page. On peut ajouter landscape à la suite des quatre marges pour produire un document au format “paysage”.
linestretch:permet, si nécessaire, d’augmenter ou de diminuer l’interligne (1 est la valeur par défaut).
fontsize:la taille des caractères est = 10, 11 ou 12 pt. Il est possible d’avoir d’autres tailles, 8, 9, 14, 17 ou 20 pt, après avoir remplacé article par extarticle dans “documentclass”.
toc:true/false (crée une table des matières en début du document). On peut aussi utiliser lof: et lot: pour les tables de figures et de tableaux.
toc depth:de 1 à x (précise la profondeur de cette table des matières).
numbersections:true/false (pour numéroter automatiquement les titres). Pour empêcher la numérotation d’un titre en particulier, il faut ajouter “{-}” à la suite du titre, sans espace.
Liens
linkcolor:par exemple green (pour définir la couleur lien interne en vert)
urlcolor:par exemple blue (pour définir la couleur des liens externe en bleu).
links-as-notes:true/false (pour transformer tous les liens en notes de bas de page).
Bibliographie
Deux variables sont indispensables pour insérer automatiquement des citations et une liste bibliographique :
bibliography:library.bib (le nom du fichier bibtex créé, par exemple, avec Zotero).
csl:apa.csl (le style bibliographique).
Métadonnées
Pour faciliter le partage et la diffusion d’un document numérique, celui-ci doit contenir sa propre description. On parle de métadonnées[2]. La structure de ces métadonnées fait l’objet de normes.
À l’heure actuelle, il n’est pas encore possible d’intégrer les 15 champs de description Dubin Core[3] dans un document Markdown mais l’utilisation de l’en-tête YAML permet néanmoins le partage des principales informations entre outils ainsi que l’alimentation automatique des bases de données.
Les éléments utilisés ici sont :
- title
- subtitle
- author
- date
- abstract
- affiliation
- keywords
- subject
- project
- modified
- right
Les cinq premiers items servent aussi pour la mise en forme. Par exemple, avec le type article, ces informations apparaissent au début du document.
Pour le champs “date:”, on peut indiquer “\today” pour avoir la date du jour et « \hhmm » pour l’heure.
En utilisant LUA[4], il est possible d’identifier et de provoquer l’affichage d’une affiliation différente pour chaque auteur mais il est déjà possible de renseigner plusieurs auteurs avec des affiliations différentes (qui apparaîtront en notes en bas de page) en utilisant les notes :
author:
– Auteur 1 ^[Affiliation auteur 1]
– Auteur 2 ^[Affiliation auteur 2]Pour aller plus loin, on peut consulter la liste complète[5] des variables possibles à insérer dans l’entête YAML pour produire des pdf.
