Le parseur Markdown utilisé par mdBook est pulldown-cmark

C’est une bibliothèque écrite en Rust qui implémente l’analyseur CommonMark. ¹

pulldown-cmark est développé sous forme d’un analyseur par flux (pull parser).

Où l’on parle de pulldown-cmark

Dans la documentation mdBook, pulldown-cmark est abordé dans le chapitre pour les développeurs·ses décrivant le fonctionnement des préprocesseurs, dans le sous-chapitre « trucs pour développer un préprocesseurs » :

« The mdbook-markdown crate exposes the pulldown-cmark crate used by mdBook to parse Markdown. The pulldown-cmark-to-cmark crate can be used to translate events back into markdown text. » ²

« Le paquet (crate) mdbook-markdown expose le paquet pulldown-cmark utilisé par mdBook pour analyser le Markdown. Le paquet pulldown-cmark-to-cmark peut être utilisé pour traduire à nouveau ces événements en texte Markdown. »

Plus simplement, on retrouve pulldown-cmark dans la documentation du paquet (crate) mdbook-markdown :

« This crate provides functions for processing Markdown in the same way as mdBook. The pulldown_cmark crate is used as the underlying parser. This crate re-exports pulldown_cmark so that you can access its types. » ³

« Ce paquet (crate) fournit des fonctions pour traiter le Markdown de la même manière que mdBook. Le paquet pulldown_cmark est utilisé comme parseur sous-jacent. Cette caisse ré-exporte pulldown_cmark afin que vous puissiez accéder à ses types. »

Fonctionnement (pour les développeurs·ses)

L’analyse par « événements » (pull parsing)

Contrairement à d’autres parseurs qui créent un arbre complet du document en mémoire (DOM), pulldown-cmark découpe le document Markdown en un flux d’événements (stream of events).

Lorsqu’il lit un fichier source Markdown, il génère des signaux au fur et à mesure :

• Start(Heading(Level1)) : Début d’un titre de niveau 1
• Text("Mon super titre") : Le texte du titre
• End(Heading(Level1)) : Fin du titre
• Start(List) : Début d’une liste
• …

Le rôle des bibliothèques citées

• pulldown-cmark est le moteur de base qui transforme le code source Markdown en une série d’événements (flux).
• mdbook-markdown est la passerelle interne de mdBook. Elle nous donne un accès direct à ce moteur pour que nous puissions intercepter et modifier les événements à la volée.
• pulldown-cmark-to-cmark est l’outil inverse. Une fois que notre préprocesseur a intercepté et modifié les événements (par exemple en remplaçant un mot-clé ou en formatant un tableau), pulldown-cmark-to-cmark réassemble le résultat pour recréer un fichier texte Markdown.

La méthode par événements évite d’avoir à manipuler du texte brut avec des expressions régulières (Regex) complexes et risquées. Elle nous propose de manipuler des objets logiques (des titres, du texte, des liens).

1. https://github.com/pulldown-cmark/pulldown-cmark/ ↩

2. https://rust-lang.github.io/mdBook/for_developers/preprocessors.html#hints-for-implementing-a-preprocessor ↩

3. https://docs.rs/mdbook-markdown/latest/mdbook_markdown/ ↩