Markdown

Syntaxe

Syntaxe de base

Il s’agit des commandes de base que propose Markdown et qui devraient fondamentalement fonctionner dans tous les outils.

Titres

Pour afficher des titres, un ou plusieurs dièses sont placés devant le titre du niveau correspondant.

# Titre 1

## Titre 2

### Titre 3

#### Titre 4

##### Titre 5

###### Titre 6

Remarque : Il est préférable de toujours insérer une ligne vide avant un titre, car sinon les interprétations peuvent être incorrectes.

Paragraphes/Lignes

Il n’existe pas de réelles notations pour les sauts de ligne et les paragraphes ; le texte est affiché tel qu’écrit. Pour favoriser un saut de ligne, deux espaces peuvent être ajoutés à la fin de la ligne, ou alternativement, la balise HTML <br> peut être utilisée.


Première ligne avec deux espaces à la fin.  
Et maintenant la ligne suivante.

Première ligne avec la balise HTML à la fin.<br>
Et maintenant la ligne suivante.

Mise en forme du texte

Par défaut, Markdown offre la possibilité d’afficher le texte en gras et/ou en italique.

Pour afficher un texte en gras, la partie de texte correspondante est écrite entre deux étoiles ou deux underscores.


J'ai aussi du **texte en gras**.

J'ai aussi du __texte en gras__.

Et voici du **texte en gras** au milieu.

Pour afficher un texte en italique, la partie de texte correspondante est écrite entre une étoile ou un underscore.


J'ai aussi du *texte en italique*.

J'ai aussi du _texte en italique_.

Et voici du *texte en italique* au milieu.

Bien sûr, il est aussi possible de les combiner :

Pour afficher un texte en gras et en italique, la partie de texte correspondante est écrite entre trois étoiles ou trois underscores.


J'ai aussi du ***texte en gras et en italique***.

J'ai aussi du ___texte en gras et en italique___.

Et voici du ***texte en gras et en italique*** au milieu.

Citations (Blockquotes)

Pour citer un texte sous forme de bloc, il suffit de placer un signe « supérieur à » devant la ligne.


> Ce texte se trouve dans une citation.

Si la citation doit s’étendre sur plusieurs lignes, le signe « supérieur à » doit être placé au début de chaque ligne (y compris les lignes vides).


> Ce texte représente la première ligne de la citation.
> 
> Et voici la ligne suivante.

Les citations peuvent également être imbriquées ; dans ce cas, un signe « supérieur à » supplémentaire est ajouté pour le niveau ou l’indentation suivante.


> Ce texte se trouve dans une citation.
> 
>> Ce texte est imbriqué.

Listes

Les listes sont tout aussi simples et sont écrites directement dans le texte. Si la liste passe à un autre niveau, cela est permis par une indentation (4 espaces ou 1 tabulation).

Liste ordonnée

Les listes ordonnées sont générées en plaçant simplement le numéro correspondant suivi d’un point devant la ligne.


1. Premier élément
2. Deuxième élément
3. Troisième élément
    1. première indentation
    2. deuxième indentation
4. Quatrième élément

Liste non ordonnée

Les listes non ordonnées sont générées en plaçant simplement un tiret devant la ligne.


- Premier élément
- Deuxième élément
- Troisième élément
    - première indentation
    - deuxième indentation
- Quatrième élément

Liens et images

Pour afficher un lien, le texte du lien est placé entre crochets, suivi de l’URL entre parenthèses.

Les listes ordonnées sont générées en plaçant simplement le numéro correspondant suivi d’un point devant la ligne.


Mon moteur de recherche préféré est [Swisscows](https://swisscows.com/fr).

Un titre peut également être ajouté au lien sous forme d’infobulle.


Mon moteur de recherche préféré est [Swisscows](https://swisscows.com/fr "Le moteur de recherche suisse").

Comme forme abrégée, une URL peut aussi simplement être écrite entre crochets angulaires.


Mon moteur de recherche préféré est <https://swisscows.com/fr>.

Syntaxe étendue

Tableaux

Les tableaux sont définis à l’aide de barres verticales (|) et de tirets (-). La première ligne contient les en-têtes de colonnes, la deuxième ligne définit l’alignement (facultatif).

| Aligné à gauche | Centré        | Aligné à droite |
| :-------------- | :-----------: | --------------: |
| Cellule 1       | Cellule 2     | Cellule 3       |
| Cellule 4       | Cellule 5     | Cellule 6       |

Remarque : Le nombre de tirets dans la ligne de séparation est arbitraire ; seul le : pour l’alignement est important.

Blocs de code

Pour du code sur plusieurs lignes, un bloc de code est créé avec trois accents graves (```) ou avec quatre espaces par ligne. Facultativement, le langage peut être spécifié pour activer la coloration syntaxique.

```python
def hello():
    print("Bonjour le monde !")


---

#### Notes de bas de page

Les notes de bas de page sont insérées dans le texte avec `[^identifiant]` et définies à la fin du fichier avec `[^identifiant]:`.

```markdown
Voici un texte avec une note de bas de page.[^1]

[^1]: Ceci est l'explication de la note de bas de page.

Remarque : Tous les analyseurs Markdown ne prennent pas en charge les notes de bas de page – par exemple, Hugo nécessite goldmark avec l’option activée.

ID pour les titres

Les titres peuvent être dotés d’un ID pour y accéder directement (par exemple, pour les tables des matières ou les liens d’ancrage).

## Titre avec ID {#mon-id}

[Lien vers le titre](#mon-id)

Remarque : Dans Hugo, enableInlineShortcodes = true doit être activé dans la configuration.

Listes de tâches

Les listes de tâches (checklists) sont créées avec - [ ] pour les éléments non cochés et - [x] pour les éléments cochés.

- [x] Tâche terminée
- [ ] À faire
- [ ] À faire plus tard

Remarque : Souvent utilisé dans GitHub, GitLab ou des applications de notes comme Obsidian.

Texte barré

Le texte barré est entouré de deux tildes (~~).

Ce texte est ~~barré~~.

Émojis

Les émojis peuvent être insérés directement (par exemple, 😊) ou avec des codes courts comme :smile: (selon l’analyseur).

Je suis de bonne humeur aujourd'hui 😊

Remarque : Dans Hugo, les émojis doivent être explicitement activés (enableEmoji = true).

Mise en évidence du texte

Certains analyseurs (par exemple, Hugo avec Goldmark) prennent en charge la mise en évidence avec == :

Ce texte est ==mis en évidence==.

Remarque : Non standardisé – ne fonctionne pas partout.

Indices/Exposants

Les indices (H₂O) et les exposants (x²) sont représentés respectivement avec ~ et ^ – mais uniquement dans certaines extensions comme Pandoc ou Hugo avec un analyseur spécial.

L'eau est H~2~O.  
x^2^ est x au carré.

Remarque : Ne fait pas partie de la norme CommonMark – Fonctionne, par exemple, dans Hugo avec goldmark et l’option activée.

Utilisation

Markdown ne représente pas un système en soi, mais se contente d’une syntaxe ouverte et librement disponible. On pourrait comparer Markdown à un langage de script intégrable. C’est certainement aussi la raison pour laquelle tant de systèmes prennent en charge Markdown et que le langage est ainsi si polyvalent.

Systèmes Wiki

Les systèmes Wiki tels que Mediawiki (sur lequel Wikipédia est basé), dokuWiki, ou les fonctions wiki intégrées comme celles de GitHub ou GitLab utilisent standardement Markdown pour la gestion du contenu.

Les wikis sont avant tout là pour présenter du contenu, dans le domaine Git, la documentation du logiciel proposé. Grâce à la syntaxe simple, ceux-ci peuvent également être créés et gérés par des non-spécialistes.

Notes

Les applications de notes largement disponibles (ou parfois aussi appelées wikis de bureau) reposent également sur Markdown pour la gestion du contenu. Souvent, un éditeur WYSIWYG intégré est fourni, mais il utilise Markdown en arrière-plan. Il est également généralement possible de passer au texte source et d’éditer directement. Des exemples incluent Zim, Zettlr, QOwnNotes, et Logseq dans le domaine open source, ou des variantes populaires comme Evernote, Obsidian, ou Joplin.

Sites Web

Dans le domaine des sites Web, Markdown apparaît de deux manières. D’une part, les systèmes de gestion de contenu connus (comme WordPress et Drupal) offrent souvent des plugins/modules pour publier du contenu en Markdown. Mais outre les CMS, il existe aussi des SSG, appelés générateurs de sites statiques, comme Hugo ou Jekyll. De plus, il existe des systèmes similaires spécialisés dans la documentation technique comme MKDocs, Sphinx, ou Docusaurus. Ici aussi, tout le contenu est créé en Markdown puis converti en sites web statiques à l’aide d’un préprocesseur, qui peuvent ensuite être publiés.

Présentations/Cours

Outre les sites web, des présentations peuvent également être créées avec Markdown. Cependant, il ne s’agit pas de présentations PowerPoint, mais celles-ci sont dynamiquement converties en éléments web à l’aide de préprocesseurs. Des exemples incluent Marp, remarkJS, ou Cleaver. Spécifiquement pour les cours en ligne, l’extension Markdown LiaScript est appropriée.

Documents

Il manque certainement à Markdown certaines fonctionnalités qu’un traitement de texte comme MS Word ou LibreOffice Writer peut offrir, mais il est parfaitement suffisant pour des documents simples tels que des lettres.

Conclusion

Avantages

Markdown a une syntaxe simple et claire et est donc facile à apprendre. Les documents Markdown ont également l’avantage d’être facilement lisibles même en texte source. Ils sont donc à la fois lisibles par machine et par l’homme. Ce dernier grâce à la syntaxe simple et directe sans surcharge. La large diffusion de Markdown et son intégration dans tant d’outils parlent également d’eux-mêmes.

Inconvénients

Outre les avantages clairs, il y a malheureusement aussi des aspects négatifs à signaler concernant Markdown.

Markdown convient très bien pour des articles et des notes qui ne sont pas structurés de manière trop complexe. Si l’on souhaite créer davantage, par exemple des documents grands et complexes, tels que des livres entiers, des fonctions utiles comme une table des matières ou la possibilité d’imbriquer des fichiers en utilisant “Include” manquent.

Bien qu’il existe une norme Markdown avec CommonMark, la forte diffusion a néanmoins conduit à de nombreux “dialectes”, car de nombreux outils étendent la syntaxe standard avec leurs propres commandes. Par conséquent, les documents Markdown provenant de différents systèmes ne sont pas nécessairement compatibles entre eux.