blog » self-hosted » markdown

Écrire des pages en Markdown

Si vous êtes encore là, vous serez peut-être intéressé par Comment ajouter de la couleur aux fenced-code-blocks.

Cette section présente le fonctionnement du Markdown sur ce site, la façon dont les blocs de code sont rendus, le comportement des admonitions, ainsi que quelques fonctionnalités supplémentaires prises en charge par ma configuration.
Si vous êtes habitué au Markdown façon GitHub, la plupart des éléments vous sembleront familiers — sauf ceux qui ne le sont absolument pas.

Blocs de code et coloration syntaxique

L’extra fenced-code-blocks permet d’écrire des blocs de code avec coloration syntaxique à l’aide de triples apostrophes (''' dans l’exemple ci-dessous).

Voici un petit exemple en Python :

'''python
import numpy as np

print(np.sum(range(100)))
'''

… qui donne ceci :

import numpy as np

print(np.sum(range(100)))

Si vous oubliez un import ou écrivez mal un nom de fonction, le coloriseur ne vous jugera pas. Moi peut-être — mais pas lui.

Le code inline fonctionne comme d’habitude, par exemple mv /some/path /some/other/path pour replacer un fichier perdu, ou simplement pour démontrer votre précision de frappe impeccable.

Le texte barré est également supporté : très utile pour rayer les mauvaises idées.

Admonitions (Important !)

Ce site utilise l’extra admonitions de markdown2, qui n’utilise pas la même syntaxe que GitHub.
C’est à la fois plus flexible et plus obscur — un combo parfait pour un blog auto-hébergé.

Les admonitions existent en sept saveurs :

• Note
• Tip
• Important
• Warning
• Caution / Danger
• Error

Chaque type possède son propre style dans le HTML final.
Utilisez-les pour mettre en valeur une information, prévenir votre futur-vous d’une mauvaise décision, ou attirer l’attention sur un détail critique.

Exemple de Tip

Syntaxe expliquée

Anatomie d’une admonition

Pièges fréquents

Citations (Blockquotes)

Les citations utilisent la syntaxe classique de Markdown :

Bonjour

Écrite ainsi :

> Bonjour

Pratique pour les notes, les citations, et les commentaires passifs-agressifs.

Support LaTeX

Les expressions mathématiques sont rendues grâce à l’extra latex.

Par exemple : $$\sum_{i=1}^n i = \frac{n(n+1)}{2}$$

produit :

Les blocs, l’inline math, et même les équations contenant de vrais nombres (pas seulement du flexing symbolique) fonctionnent.

Tableaux

Les tableaux sont entièrement supportés et se comportent comme prévu :

Idéal pour structurer des informations, comparer des éléments, ou lister tous les services que vous aviez oubliés de configurer correctement la première fois.