YAML

Pour rappel, Pandoc prend en charge les entêtes YAML pour les fichiers Markdown. Cet acronyme n'est pas simple à traduire, il vient de YAML Ain’t Markup Language telle que le définit le site yaml.org.

Ci-dessous un exemple d'entête YAML plus complet avec une série d'instructions pour la mise en forme et les métadonnées du document produit (ici pdf).

---

# format du document

documentclass: article
header-includes:
    - \usepackage[french]{babel} 
    - \usepackage[utf8]{inputenc}
    - \usepackage[a4paper, top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
linestretch: 1
fontsize: 11pt
toc: false
toc_depth:
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 les possibilités de *Markdown* ...
keywords: Markdown, rédiger
subject: écriture numérique ouverte
Modified: 9 décembre 2021
right: CC-BY 0.4

# bibliographie

bibliography: library.bib
csl: apa.csl

# liens

links-as-notes: true
linkcolor: blue
---

Pour la rendre plus lisible, il est possible d'insérer des commentaires dans l'entête YAML.

Page

La mise en forme sera différente pour ces différents types.

Dans l'exemple ci-dessus la première ligne 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), la deuxième va préciser le code de caractères utilisé (ici UTF8) et la troisième va formater la page (geometry). On peut ajouter landscape à la suite des quatre marges pour produire un document au format "paysage".

Il est possible d'ajouter de nombreuses options dans header-includes via des packages LaTeX voir "pour aller plus loin".

Colonnes

L'utilisation, dans l'entête YAML, de :

classoption:
    - twocolumn

va provoquer l'affichage en deux colonnes de tout le document. Si vous ne souhaitez mettre en deux colonnes qu'une partie du document, ajoutez dans l'entête YAML, dans la section header-includes: :

    - \usepackage{multicol}
    - \newcommand{\hideFromPandoc}[1]{#1}
    - \hideFromPandoc{
            \let\Begin\begin
            \let\End\end}

et encadrer la partie du document à mettre en colonnes (ici deux) avec :

\Begin{multicols}{2}

et :

\End{multicols}

Entête et pied de pages

Pour ajoutez des entêtes et pieds de page dans le document, il faut compléter l'entête YAML, dans la section header-includes:, avec :

    - \usepackage{lastpage}
    - \usepackage{fancyhdr}
    - \pagestyle{fancy}
    - \fancyhead[L]{texte en haut et à gauche}
    - \fancyhead[C]{texte en haut et au centre}
    - \fancyhead[R]{texte en haut et à droite}
    - \fancyfoot[L]{texte en bas et à gauche}
    - \fancyfoot[C]{texte en bas au centre}
    - \fancyfoot[R]{Page \thepage \hspace{1pt} / \pageref{LastPage}}

Avec cet exemple, dans le bas de la page, vous verrez apparaître à droite le numéro de la page, suivi du nombre de pages du document. Vous pouvez ne pas utiliser cette fonction et dès lors ne pas ajouter la ligne - \usepackage{lastpage} dans l'entête et ne mettre que \thepage.

Caractères

Il est possible d'avoir d'autres tailles, 8, 9, 14, 17 ou 20pt, après avoir remplacé article par extarticle dans "documentclass".

Même si la police de caractères par défaut (lmodern) fait très "pro", LaTeX propose plusieurs autres polices pour la création des documents pdf.

Ici encore, ce sera directement via une instruction dans l'entête YAML. Voici quelques polices à tester (en ajoutant - \usepackage{nom_de_la_police} dans la section header-includes:) :

Pour une présentation plus complète des polices utilisables avec LaTeX, voir sur le site Cuk.ch.

Images

Pour insérer un logo sur la première page, ajouter dans l'entête YAML, dans la section header-includes: :

    - \usepackage{wallpaper}

et au tout début du document (après l'entête YALM) :

\ThisULCornerWallPaper{0.2}{image.png}

ULCorner dans l'instruction signifie Upper Left Corner, il est aussi possible de placer le logo sur la droite en remplaçant ULCorner par URCorner ou d'en placer deux (un à gauche et un à droite).

Si vous gérez les entêtes et pieds de pages (voir ci-dessus), vous pouvez ajouter (enidessous de la commande précédente), pour les désactiver sur la première page :

\thispagestyle{empty}
\setcounter{page}{1}

On peut aussi insérer une image au-dessus (ou en-dessous) du titre et ajoutant :

title: |
    ![](logo.png)
    Titre

Cette image peut avoir la taille de la page et dès lors constituer la couverture du document.

Titres et table des matières

On peut aussi utiliser lof: et lot: pour les tables de figures et de tableaux.

Pour empêcher la numérotation d'un titre en particulier, il faut ajouter "{-}" à la suite du titre, sur la même ligne.

Liens

Bibliographie

Deux variables sont indispensables pour insérer automatiquement des citations et une liste 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. La structure de ces métadonnées fait l’objet de normes.

Dans un document Markdown, les métadonnées se placent dans l'entête YAML.

À l'heure actuelle, il n'est malheureusement pas encore possible d'intégrer les 15 champs de description Dubin Core dans un document Markdown mais l'utilisation de l'entê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 :

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.

Exemple de début d'un document de type "article" avec affichage des cinq premières métadonnées

 

Pour le champs "date:", on peut indiquer "\today" pour avoir la date du jour.

En utilisant LUA, 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 affiliation différentes (qui apparaîtront en note en bas de page) en utilisant les notes :

author:
    - Auteur 1 ^[Affiliation auteur 1]
    - Auteur 2 ^[Affiliation auteur 2]

 

Il est possible d'ajouter d'autres directives de mise en forme spécifiques à LaTeX (y compris le choix de Templates de mise en forme spécifique). Cependant, on arrive alors à un niveau de complexité plus élevé qui va à l'encontre de l'intérêt de cette méthode basée sur la simplicité.

 

Pour rappel, il est possible de mettre l'ensemble du contenu de l'entête YAML dans un fichier séparé, à appeler lors de la création du fichier pdf.