Aller au contenu

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
# import du package
import markdown

# texte en markdown
texte_en_markdown = """# Super tutoriel sur la dernière techno fun en géomatique

Bienvenue dans mon **super** tutoriel, dans lequel on va apprendre :

1. à installer la techno fun du moment
2. à l'utiliser dans 2 cas d'usage :
    - analyser la répartition spatiale des poules en batterie
    - cartographier les flux de communications entre les membres de Geotribu

> Source : [*Geotribu*](https://static.geotribu.fr)

"""

# conversion en HTML
texte_en_html = markdown.markdown(texte_en_markdown, output_format="html5")

# écriture du fichier html
with open("super_tuto.html", "w", encoding="utf-8", errors="xmlcharrefreplace") as output_file:
    output_file.write(texte_en_html)

Le fichier HTML en sortie :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<h1>Super tutoriel sur la dernière techno fun en géomatique</h1>
<p>Bienvenue dans mon <strong>super</strong> tutoriel, dans lequel on va apprendre :</p>
<ol>
<li>à installer la techno fun du moment</li>
<li>à l'utiliser dans 2 cas d'usage :<ul>
<li>analyser la répartition spatiale des poules en batterie</li>
<li>cartographier les flux de communications entre les membres de Geotribu</li>
</ul>
</li>
</ol>
<blockquote>
<p>Source : Geotribu</p>
</blockquote>

Si on ouvre le fichier super_tuto.html dans un navigateur :

Markdown rapide exemple

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 :

Trouver des extensions :

Info

Consulter la liste des extensions activées dans le fichier de configuration.


Dernière mise à jour: 14 septembre 2020
Contributions à cette page : Julien Moura

Commentaires