4 YAML

Pour rappel, Pandoc prend en charge les en-tê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[1].

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).

L’entête YAML est précédée et suivie de trois tirets simples :

–  – –

# 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 (comme ci-dessus) des commentaires dans l’entête YAML.

Page

documentclass: avec book ou report ou article (et également chapter ou part).

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

header-includes: une série de commandes directes LaTeX.

Dans l’exemple ci-dessus , l’instruction \usepackage[french]{babel} 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), l’instruction \usepackage[utf8]{inputenc} va préciser le code de caractères utilisé (ici UTF8) et la suivante 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” dans le chapitre « sources ».

linestretch: permet, si nécessaire, de régler l’interligne (1 est la valeur par défaut).

Colonnes

L’utilisation, dans l’entête, de :

classoption:
– twocolumn

va provoquer l’affichage en deux colonnes de tout le document. Si vous souhaitez ne 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}

En-tête et pied de pages

Pour ajoutez des en-tê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. Si vous n’ajoutez pas la ligne – \fancyhead[L]{}, fancy ajoutera, en haut, à gauche, un titre courant à la page (le premier titre de niveau 2). Le comportement est le même pour la zone en haut, à droite, pour le titre de niveau 1.

Caractères

fontsize: la taille des caractères = 10, 11 ou 12pt.

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:) :

  • times
  • palatino
  • bookman
  • newcent
  • helvet (ajouter \renewcommand{\familydefault}{\sfdefault} sur la ligne suivante dans la section header-includes:)
  • avant (idem)

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}
\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

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, sur la même ligne.

Liens

linkcolor: blue (pour définir la couleur des liens).

links-as-notes: true/false (créer des notes de bas de page pour tous les liens).

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.

Dans un document Markdown, les métadonnées se placent dans l’en-tête YAML.

À l’heure actuelle, il n’est malheureusement 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.

 

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[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 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’en-tête YAML dans un fichier séparé, à appeler lors de la création du fichier pdf.


Licence

Symbole de Licence Creative Commons Attribution 4.0 International

Markdown & vous Droit d'auteur © 2023 par Bernard Pochet est sous licence Licence Creative Commons Attribution 4.0 International, sauf indication contraire.

Partagez ce livre