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://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.

  1. étape où un contributeur propose d'intégrer ses modifications dans le socle principal du projet. Voir la documentation de GitHub. ↩

Commentaires