Module `markdown`

Le module markdown convertit du texte markdown en HTML, en texte brut, ou vers un markdown normalisé, en s'appuyant sur Markdig, une bibliothèque .NET conforme CommonMark avec un riche jeu d'extensions optionnelles (tableaux, notes de bas de page, listes de tâches, etc.).

local markdown = require("markdown")

local html = markdown.tohtml("# Titre\n\nDu texte en **gras**.")
print(html)
--> <h1>Titre</h1>
--> <p>Du texte en <strong>gras</strong>.</p>

Vue d'ensemble

Fonction	Description
`markdown.tohtml(text [, extensions])`	Convertit du markdown en HTML
`markdown.totext(text [, extensions])`	Convertit du markdown en texte brut (mise en forme retirée)
`markdown.normalize(text [, extensions])`	Réécrit du markdown sous une forme normalisée

Les trois fonctions retournent une chaîne, et acceptent en argument 2 (optionnel) une chaîne d'extensions Markdig — voir « Extensions » ci-dessous. Sans argument 2, seul CommonMark de base est actif (pas de tableaux, pas de notes de bas de page, etc.).

`markdown.tohtml(text [, extensions])`

Convertit text (markdown) en HTML.

print(markdown.tohtml("Un lien : [YScript](https://example.com)."))
--> <p>Un lien : <a href="https://example.com">YScript</a>.</p>

print(markdown.tohtml("| a | b |\n|---|---|\n| 1 | 2 |", "pipetables"))
--> <table>...</table>

`markdown.totext(text [, extensions])`

Convertit text (markdown) en texte brut : la mise en forme (emphase, titres, liens, ...) est retirée, seul le contenu textuel est conservé.

print(markdown.totext("# Titre\n\nDu texte en **gras**, et un [lien](https://example.com)."))
--> Titre
--> Du texte en gras, et un lien.

`markdown.normalize(text [, extensions])`

Réécrit text (markdown) sous une forme normalisée (espacement et marqueurs d'emphase cohérents), sans passer par le HTML. Utile pour reformater un fichier .md de façon homogène.

print(markdown.normalize("Titre\n=====\n\n*  item 1\n*  item 2"))
--> # Titre
-->
--> * item 1
--> * item 2

Extensions

Par défaut, seul CommonMark (la spécification de base du markdown) est actif. Les extensions Markdig, désactivées par défaut, s'activent via l'argument extensions : une chaîne contenant un ou plusieurs noms d'extension séparés par +.

markdown.tohtml(text, "advanced")                 -- toutes les extensions "avancées" courantes
markdown.tohtml(text, "pipetables+autolinks")      -- seulement celles-ci

* marque les extensions déjà incluses dans advanced — inutile de les combiner explicitement avec advanced, seulement pour les activer seules ou avec d'autres extensions hors advanced.

Nom	Effet
`advanced`	active d'un coup le jeu d'extensions "avancées" ci-dessous marquées `*`
`pipetables` *	tableaux au format GitHub (`\\| a \\| b \\|`)
`gridtables` *	tableaux au format "grid table" (bordures ASCII)
`footnotes` *	notes de bas de page (`[^1]`)
`footers` *	bloc de pied de document
`citations` *	citations (`""texte""`)
`attributes` *	attributs génériques sur les éléments (`{#id .classe}`)
`abbreviations` *	abréviations (`*[HTML]: HyperText Markup Language`)
`emojis`	émojis et smileys (`:smile:`, `:-)`)
`definitionlists` *	listes de définitions
`customcontainers` *	conteneurs personnalisés (`::: nom` ... `:::`)
`figures` *	figures avec légende
`mathematics` *	formules mathématiques ( $...$ , `$$...$$`)
`bootstrap`	classes CSS Bootstrap sur certains éléments générés
`medialinks` *	liens vers médias (audio/vidéo/iframe) rendus en balises adaptées
`smartypants`	remplacement typographique (guillemets, tirets, points de suspension)
`autoidentifiers` *	identifiants générés automatiquement sur les titres (ancre `#titre`)
`tasklists` *	listes de tâches (`- [ ]`, `- [x]`)
`diagrams` *	blocs de diagrammes (mermaid, nomnoml)
`nofollowlinks`	ajoute `rel="nofollow"` aux liens générés
`noopenerlinks`	ajoute `rel="noopener"` aux liens générés
`noreferrerlinks`	ajoute `rel="noreferrer"` aux liens générés
`nohtml`	désactive le HTML brut inclus dans le markdown source
`yaml`	reconnaît (sans le rendre) un bloc d'en-tête YAML (`---`)
`autolinks` *	détecte automatiquement les URLs/adresses email en texte brut
`emphasisextras` *	marqueurs d'emphase supplémentaires (souligné, barré, ...)
`listextras` *	numérotation de liste étendue (`a.`, `i.`, ...)
`hardlinebreak`	un retour à la ligne simple produit un saut de ligne (`<br>`)
`alerts` *	blocs d'alerte GitHub (`> [!NOTE]`, `> [!WARNING]`, ...)

Un nom d'extension inconnu (typo, extension inexistante) fait lever une erreur script.

local ok, err = pcall(markdown.tohtml, text, "not-an-extension")
if not ok then
    print("extensions invalides : " .. err)
end

Exemple complet

local markdown = require("markdown")

local doc = [[
# Notes

Une liste de tâches :

- [x] Écrire le module
- [ ] Écrire les tests

| Fonction | Fait |
|----------|------|
| tohtml   | oui  |
| totext   | oui  |
]]

print(markdown.tohtml(doc, "tasklists+pipetables"))
print(markdown.totext(doc))

Module markdown