Markdown et pandoc

Du HTML au Markdown

L’HTML est devenu un standard. Mais comment écrire en HTML?

L’HTML est très verbeux et cela prend trop de temps d’écrire les balises.

Les balisages légers sont une solution à ce problème. L’idée est de représenter l’HTML de manière plus légère. On fait ensuite un système de correspondances et on crée un parseur pour l’appliquer.

Faisons un exemple.

Pour écrire un titre de niveau 1 en HTML, on écrit:

<h1>Un document en HTML</h1>

La syntaxe des balises occupe 9 caractères: <h1></h1>

En markdown:

# Un document en HTML

La syntaxe pour exprimer le titre de niveau 1 occupe 2 caractères: le # et un espace.

Un autre exemple, un paragraphe avec un italique:

<p>Un texte pour essayer. Je mets de l'<i>italique</i></p>

14 caractères pour les balises.

En markdown:

Un texte pour essayer. Je mets de l'_italique_.

Le paragraphe est balisé avec un saut de ligne et l’italique avec deux _. Donc au total, 3 caractères à la place de 14.

Ensuite il faut juste faire la correspondance entre les syntaxes.

Un langage de balisage léger implique donc:

1. Une syntaxe
2. Un parseur

Le parseur passe sur le texte, cherche les patrons syntaxiques et structure le texte sur cette base. Il va “comprendre” que ce qui suit un # et un espace est un titre de niveau 1.

Le parseur applique donc une série de règles pour structurer le document à partir de la syntaxe. Le premier parseur était en perl. Aujourd’hui il y a un très grand nombre de parseurs markdown – pandoc en propose un.

L’histoire de Markdown

Capture d’écran du site de John Gruber

Source

fr

Markdown est crée en 2004 par John Gruber qui s’inspire d’atx, proposé en 2002 par Aaron Swartz.

Gruber crée à la fois la syntaxe et le parseur Perl.

Markdown n’est pas un standard

Markdown ne fait pas l’objet d’une spécification. C’est une syntaxe proposée et ensuite reprise par des communautés qui se l’approprient comme elles le souhaitent. C’est la raison pour laquelle il y a plusieurs “goûts” de markdown. Certaines syntaxes changent selon les contextes d’utilisation.

Fauchié revient sur cette question ici (Fauchié 2024).

Commonmark

Commonmark est une tentative de standardisation de markdown – réalisé par John MacFarlane, le créateur de pandoc.

Mais est-ce possible de standardiser? Fauchié (Fauchié 2024) souligne que non, et renvoie à MacFarlane (MacFarlane, s. d.)

Les goûts de Markdown

Chacun s’approprie markdown de manière différente. Il y a donc plusieurs “goûts” de markdown. Par exemple:

• GitHub Flavored Markdown
• Pandoc flavored markdown
• Markdown extra
• Multi markdown
• Critic Markup

D’autres balisages légers

Il y a plusieurs autres approches pour faire du balisage léger. Par exemple:

• AsciiDoc
• reStructuredText
• Creole
• Wikitext
• Djot : créé par John MacFarlane, proche du md pandoc flavored

Les métadonnées: yaml

Yaml est un format très simple pour exprimer des métadonnées. Il fonctionne tout simplement avec des clés-valeurs exprimées comme suit:

title: Mon titre
author: Nom 
subject: blabla
keywords:

En utilisant markdown + yaml on peut exprimer des structures textuelles assez complexes…

Pandoc

Pandoc est un outil de conversion créé par John MacFarlane en 2006.

Pandoc permet de convertir des documents numériques en ligne de commande.

La commande pandoc appelle un ou plusieurs fichiers en entrée, un format de sortie ou de conversion, et le fichier de sortie.

• par exemple pour convertir un fichier au format Markdown en HTML: pandoc -f md -t html fichier.md -o fichier.html

La commande pandoc est hautement configurable. Il faut consulter la documentation régulièrement en fonction de vos besoins d’éditeur.

Pour convertir d’un format à l’autre, Pandoc utilise des templates ou des modèles de documents. Il est possible de personnaliser ces modèles, comme nous allons le voir dans la suite de l’atelier.

Quelques options de la commande Pandoc à connaître :

• --standalone (produit un document complet incluant les métadonnées)
• --bibliography=references.bib (spécifie un fichier de références bibliographiques)
• --template=mytemplate.html (spécifie un modèle)
• --toc (table of contents)
• --help (résume les options existantes)

Caractéristiques de Pandoc

• Il a été créé par John MacFarlane, un philosophe
• Il est largement utilisé par la communauté scientifique (notamment en sciences humaines, mais pas seulement)
• C’est un convertisseur, mais avec le temps les pratiques en ont fait un outil pour transformer md vers n’importe quel autre format.
• Il est écrit en haskell.
• Il est composé par:
  • une série de parseurs (readers): ils lisent le texte en entrée et le transforment dans l’AST de pandoc
  • une série de “writers” : ils prennent le AST et le transforment dans le format de sortie

L’AST de pandoc

Depuis la version 3.8 le AST (Abstract Syntax Tree) de pandoc est représenté en json et en XML (avant c’était seulement en json).

Par exemple, si nous avons le document md suivant:

---
title: Titre
---

## Introduction

Mon intro avec une note^[Note]

La commande pandoc -t json aura comme output l’ast:

{
    "pandoc-api-version": [
        1,
        23,
        1
    ],
    "meta": {
        "title": {
            "t": "MetaInlines",
            "c": [
                {
                    "t": "Str",
                    "c": "Titre"
                }
            ]
        }
    },
    "blocks": [
        {
            "t": "Header",
            "c": [
                2,
                [
                    "introduction",
                    [],
                    []
                ],
                [
                    {
                        "t": "Str",
                        "c": "Introduction"
                    }
                ]
            ]
        },
        {
            "t": "Para",
            "c": [
                {
                    "t": "Str",
                    "c": "Mon"
                },
                {
                    "t": "Space"
                },
                {
                    "t": "Str",
                    "c": "intro"
                },
                {
                    "t": "Space"
                },
                {
                    "t": "Str",
                    "c": "avec"
                },
                {
                    "t": "Space"
                },
                {
                    "t": "Str",
                    "c": "une"
                },
                {
                    "t": "Space"
                },
                {
                    "t": "Str",
                    "c": "note"
                },
                {
                    "t": "Note",
                    "c": [
                        {
                            "t": "Para",
                            "c": [
                                {
                                    "t": "Str",
                                    "c": "Note"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Et en XML (pandoc -t xml):

<?xml version='1.0' ?>
<Pandoc api-version="1,23,1">
<meta>
<entry key="title">
<MetaInlines>Titre</MetaInlines>
</entry>
</meta>
<blocks>
<Header id="introduction" level="2">Introduction</Header>
<Para>Mon intro avec une note<Note><Para>Note</Para>
</Note></Para>
</blocks>
</Pandoc>

Citeproc

C’est un module de pandoc qui permet de processer des références structurées, notamment en bibtex.

Balisage sémantique en HTML

Html est facilement customisable pour un usage sémantique. Une manière pour sémantiser un texte est d’utiliser des attributs ou des classes.

Avantages: - pas besoin de valider contre un schéma - très simple à faire - complètement libre

Inconvénients: - pas de validation - structure non nécessairement sémantique (confusion avec forme)

Un exemple:

<div class="infogeo">
<p><span id="https://www.wikidata.org/wiki/Q1524" class="ville" data-gps="37.58.46N, 23.42.58E">Athène</span> est la capitale de la Grèce.</p>
</div>

Pandoc permet d’exprimer ce type d’information en md:

::: {.infogeo}

[Athènes]{.ville id="https://www.wikidata.org/wiki/Q1524" gps="37.58.46N, 23.42.58E"} est la capitale de la Grèce.

:::