reStructuredText vs Markdown : Référence rapide
Référence syntaxique côte à côte pour les deux langages de balisage.
Note
Les éléments marqués [identique] utilisent une syntaxe identique ou quasi-identique dans les deux langages. Les éléments marqués [différent] ont une syntaxe significativement différente. Les notes sur Markdown s'appliquent principalement à CommonMark / GitHub Flavored Markdown (GFM) sauf indication contraire.
Formatage en ligne
Italique [identique]
| reStructuredText | Markdown |
|---|---|
| *italic* | *italic* or _italic_ |
Gras [identique]
| reStructuredText | Markdown |
|---|---|
| **bold** | **bold** or __bold__ |
Gras italique
| reStructuredText | Markdown |
|---|---|
| Non supporté nativement | ***bold italic*** |
Code en ligne [similaire]
| reStructuredText | Markdown |
|---|---|
| ``code`` | `` code `` |
| Double apostrophes | Apostrophe simple |
Texte barré
| reStructuredText | Markdown |
|---|---|
| Non natif ; utiliser un | ~~text~~ |
| rôle ou du HTML brut | (GFM / étendu) |
Titres
H1
| reStructuredText | Markdown |
|---|---|
Title
|
# Title |
=====
|
|
Soulignement avec = (longueur identique requise)
|
H2
| reStructuredText | Markdown |
|---|---|
Section
|
## Section |
-------
|
|
Soulignement avec - (ou tout signe
|
|
de ponctuation, utilisé de façon constante)
|
H3
| reStructuredText | Markdown |
|---|---|
Subsection
|
### Subsection |
~~~~~~~~~~
|
|
Tilde ou tout nouveau caractère de ponctuation
|
Variante avec surlignement
| reStructuredText | Markdown |
|---|---|
==========
|
Non supporté |
Title
|
|
==========
|
|
Surlignement + soulignement pour le niveau supérieur
|
Listes
Liste non ordonnée [similaire]
| reStructuredText | Markdown |
|---|---|
| - item | - item |
| - item | - item |
| - item | - item |
| Aussi * or + | Aussi * or + |
Liste ordonnée [similaire]
| reStructuredText | Markdown |
|---|---|
| 1. first | 1. first |
| 2. second | 2. second |
| 3. third | 3. third |
| Aussi #. pour | |
| la numérotation auto |
Liste imbriquée
reStructuredText:
- item - nested - item Ligne vide + indentation de 2 espaces requise.
Markdown:
- item - nested - item Indenter avec 2 à 4 espaces.
Liste de définitions
| reStructuredText | Markdown |
|---|---|
term
|
Non standard ; utiliser du HTML |
`` Definition text here.``
|
ou une extension |
La définition indentée suit le terme
|
Liens & Images
Lien en ligne [différent]
| reStructuredText | Markdown |
|---|---|
| `` Link text `` | [Link text](URL) |
| Apostrophe, texte, URL entre | |
| chevrons, souligné final |
Lien par référence
reStructuredText:
`Link text`_ .. _Link text: URL
Markdown:
[Link text][id] [id]: URL
URL brute
| reStructuredText | Markdown |
|---|---|
| https://example.com | <https://example.com> |
| Lien automatique | Les chevrons forcent le lien |
Image
reStructuredText:
.. image:: path/img.png :alt: Alt text :width: 400px
Markdown:
Ancre interne
reStructuredText:
.. _my-label: :ref:`my-label`
Markdown:
[text](#heading-id) Slugs de titres uniquement (GFM).
Blocs de code
Bloc de code simple
reStructuredText:
:: code here ``::`` en fin de paragraphe, indentation de 3+ espaces.
Markdown:
``` code here ``` Délimité par des triples apostrophes.
Bloc de code avec langage
reStructuredText:
.. code-block:: python import sys
Markdown:
```python import sys ```
Inclure un fichier externe
reStructuredText:
.. literalinclude:: file.py :language: python
Markdown : Non supporté nativement.
Éléments de bloc
Citation en bloc
| reStructuredText | Markdown |
|---|---|
| Indenter avec des espaces``::`` | > Quoted text here. > Continues here. |
| Le texte indenté devient | |
| une citation en bloc. |
Ligne horizontale
| reStructuredText | Markdown |
|---|---|
| ---- | --- or *** |
| Quatre tirets ou plus | Trois -/*/_ ou plus sur leur propre ligne |
Saut de ligne
reStructuredText:
| line one | line two Blocs de lignes avec le préfixe ``|``.
Markdown:
line one line two Deux espaces en fin de ligne avant le retour à la ligne.
Note / Avertissement
reStructuredText:
.. note:: Content of the note. Aussi : ``warning::``, ``tip::``, ``caution::``
Markdown : Pas de syntaxe standard ; utiliser du HTML brut ou une extension propre à l'outil.
Tableaux
Tableau simple
reStructuredText:
=== === A B === === 1 2 === === Délimiteurs ``===``.
Markdown (tableau GFM avec tubes):
| A | B | |---|---| | 1 | 2 |
Tableau en grille (complet)
reStructuredText:
+---+---+ | A | B | +===+===+ | 1 | 2 | +---+---+ Supporte les fusions de cellules et les cellules multi-lignes.
Markdown : Non supporté.
Alignement des colonnes
reStructuredText:
.. list-table:: :widths: 25 75 :header-rows: 1
Markdown:
| L | C | R | |:---|:---:|---:| Le placement des deux-points dans la ligne de séparation contrôle l'alignement.
Avancé / Spécial
Commentaire
| reStructuredText | Markdown |
|---|---|
| .. This is a comment | Pas de syntaxe de commentaire standard |
| .. sans nom de directive |
Note de bas de page
reStructuredText:
text [1]_ .. [1] Footnote text.
Markdown (GFM / Pandoc):
text [^1] [^1]: Footnote text.
Table des matières
reStructuredText:
.. contents:: TOC Title :depth: 2
Markdown : Dépend de l'outil (Pandoc, MkDocs, etc.).
Substitution / Macro
reStructuredText:
|release| .. |release| replace:: 5.0
Markdown : Non supporté.
HTML brut
reStructuredText:
.. raw:: html <div>...</div>
Markdown:
<div>HTML inline</div> La plupart des moteurs de rendu autorisent le HTML brut directement.
Directive (générique)
reStructuredText:
.. directive-name:: arg :option: value Content block.
Markdown : Pas d'équivalent ; utiliser des extensions ou des shortcodes propres à l'outil.
Résumé des différences clés
Là où RST est plus puissant
- Titres : caractères de ponctuation flexibles plutôt que des niveaux #.
- Tableaux : tableaux en grille complets avec fusions de cellules et cellules multi-lignes.
- Avertissements : .. note::, .. warning::, .. tip:: etc. intégrés.
- Directives : mécanisme d'extension général pour tout élément de niveau bloc.
- Substitutions / macros : fragments de texte réutilisables.
- Standardisation : RST via Docutils/Sphinx est bien plus uniforme que Markdown.
Là où Markdown est plus simple ou plus répandu
- Blocs de code délimités : les triples apostrophes sont plus lisibles que :: + indentation.
- HTML brut : autorisé en ligne sans directive dans la plupart des moteurs de rendu.
- Texte barré et notes de bas de page : largement disponibles en GFM.
- Popularité : GitHub, Stack Overflow, Reddit et la plupart des wikis utilisent Markdown par défaut.
La mise en garde sur la fragmentation de Markdown
Il n'existe pas de standard Markdown unique. CommonMark est ce qui s'en approche le plus, mais GitHub Flavored Markdown (GFM), Pandoc, MkDocs et Obsidian ajoutent chacun leurs propres extensions. RST via Docutils/Sphinx est nettement plus uniforme d'un outil à l'autre.