Le moteur de rendu Markdown utilisé et ses spécificités#
MkDocs et Python-Markdown#
On utilise MkDocs pour générer le site web statique (HTML/JS/CSS), outil lui-même basé sur l'implémentation de Markdown en Python : Python-Markdown.
Utiliser#
Pour comprendre le fonctionnement, rien de mieux que d'utiliser directement cette bibliothèque sous-jacente.
Après installation (python -m pip install markdown
), le fonctionnement est très simple :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
Le fichier HTML en sortie :
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Si on ouvre le fichier super_tuto.html
dans un navigateur :
Note
La bibliothèque est évidemment utilisable en ligne de commande :
python -m markdown input.md > output.html
Différences avec la syntaxe de référence#
Si Python-Markdown est quasiment compatible avec l'implémentation Markdown de référence, mais il y a quand même quelques menues différences qu'il est intéressant de connaître pour les prendre en compte.
Spécificités#
- le retrait (tabulation) est de 4 espaces
- les sauts de lignes sont significatifs
Extensions#
Certaines extensions de la syntaxe sont intégrées au site ou peuvent l'être sur demande et après examen technique. Elles permettent d'ajouter des fonctionnalités et d'enrichir les possibilités rédactionnelles, dont certaines sont décrites dans des guides dédiés :
- ajouter des attributs de style à des images
- ajouter un effet "lightbox" (mise en avant et galerie) à des images
- intégrer des diagrammes UML
Trouver des extensions :
- les extensions de la bibliothèque Python-Markdown
- PyMdown Extensions.
Info
Consulter la liste des extensions activées dans le fichier de configuration.
Commentaires
Une version minimale de la syntaxe markdown est acceptée pour la mise en forme des commentaires.Propulsé par Isso.