Markdown : la syntaxe essentielle pour débuter

Sommaire

• Les principales syntaxes Markdown
• Créer des titres
• Créer des paragraphes
• Mettre du texte en forme
• Créer des listes
• Créer une liste de tâches avec des cases à cocher
• Ajouter un lien
• Insérer une image
• Ajouter une citation
• Insérer du code
• Créer un tableau
• Insérer un séparateur
• Les notes de bas de page

Les principales syntaxes Markdown

Les sections suivantes présentent la syntaxe à utiliser ainsi que le résultat obtenu.

À savoir : le rendu peut varier d’un outil à l’autre. La prise en charge dépend du moteur Markdown utilisé et des extensions activées, comme GitHub Flavored Markdown (GFM).

Créer des titres

Markdown propose six niveaux de titres. Ils sont créés avec un à six caractères # placés au début de la ligne.

Syntaxe

# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
###### Titre de niveau 6

Rendu

Titre de niveau 2

Titre de niveau 3

Titre de niveau 4

Titre de niveau 5

Titre de niveau 6

Conseil : réservez généralement le niveau 1 au titre principal du document, puis utilisez les niveaux suivants dans un ordre logique. Leur apparence exacte dépend des styles appliqués par l’outil utilisé.

Créer des paragraphes

Pour commencer un nouveau paragraphe, laissez simplement une ligne vide.

Syntaxe

Premier paragraphe.

Deuxième paragraphe.

Rendu

Premier paragraphe.

Deuxième paragraphe.

Mettre du texte en forme

Markdown permet de mettre facilement certains mots en évidence.

Syntaxe

**Gras**

*Italique*

***Gras et italique***

~~Texte barré~~

`Code ou commande`

Rendu

Gras

Italique

Gras et italique

Texte barré

Code ou commande

Créer des listes

Liste à puces

Syntaxe

- Premier élément
- Deuxième élément
  - Sous-élément

Rendu

• Premier élément

• Deuxième élément

  • Sous-élément

Liste numérotée

Syntaxe

1. Première étape
2. Deuxième étape
3. Troisième étape

Rendu

1. Première étape
2. Deuxième étape
3. Troisième étape

Créer une liste de tâches avec des cases à cocher

En Markdown, les cases à cocher permettent de créer une liste de tâches, aussi appelée checklist. Utilisez [ ] pour une tâche en attente et [x] pour une tâche terminée.

Syntaxe

- [ ] À faire
- [x] Terminé
- [ ] À vérifier

Rendu

• À faire
• Terminé
• À vérifier

Ajouter un lien

Un lien associe un texte visible à une adresse web ou à une autre section du document.

Lien vers une page

Syntaxe

[Composed](https://composed.fr)

Rendu

Composed

Lien vers une section

Utilisez l’identifiant généré à partir du titre de la section, précédé du caractère #. La méthode de génération de cet identifiant peut varier selon le moteur Markdown.

Syntaxe

[Consulter la section sur les tableaux](#créer-un-tableau)

Rendu

Consulter la section sur les tableaux

Lien de référence

Un lien de référence permet de placer l’adresse à part. Cette syntaxe facilite la lecture du fichier lorsque la même adresse est utilisée plusieurs fois.

Syntaxe

Consultez [Composed][site].

[site]: https://composed.fr

Rendu

Consultez Composed.

Insérer une image

Syntaxe

![Illustration du guide Markdown](md.png)

Rendu

Dans cet exemple, le texte alternatif est présent pour illustrer la syntaxe. En pratique, utilisez un texte alternatif descriptif uniquement pour une image porteuse d’information. Si l’image est purement décorative, laissez-le vide, par exemple avec ![](md.png), afin qu’elle soit ignorée par les technologies d’assistance.

Ajouter une citation

Syntaxe

> Ceci est une citation.

Rendu

Ceci est une citation.

Insérer du code

Markdown est très populaire dans la documentation technique grâce à la prise en charge du code.

Code en ligne

Syntaxe

`npm install`

Rendu

npm install

Bloc de code

Syntaxe

```javascript
function hello() {
  console.log("Bonjour");
}
```

Le nom javascript, placé après les trois accents graves d’ouverture, indique le langage utilisé. Un outil compatible peut alors appliquer une coloration syntaxique adaptée. Remplacez-le par le langage correspondant au code, comme html, css ou bash.

Rendu

function hello() {
  console.log("Bonjour");
}

Créer un tableau

Un tableau organise des informations en lignes et en colonnes. Les barres verticales | séparent les colonnes.

Il se compose de trois éléments :

• la première ligne contient les en-têtes ;
• la deuxième ligne sépare les en-têtes du contenu avec au moins trois tirets par colonne ;
• les lignes suivantes contiennent les données.

La ligne de séparation permet aussi de définir l’alignement du contenu :

• --- conserve l’alignement par défaut, généralement à gauche ;
• :--- aligne explicitement le contenu à gauche ;
• :---: centre le contenu ;
• ---: aligne le contenu à droite.

Syntaxe

| Produit | Disponibilité | Prix |
| :--- | :---: | ---: |
| SSD | En stock | 120 € |
| RAM | En rupture | 75 € |

Dans cet exemple, les produits sont alignés à gauche, la disponibilité est centrée et les prix sont alignés à droite.

Rendu

Les tableaux sont une extension courante de Markdown. Leur prise en charge peut varier selon l’éditeur ou la plateforme utilisée.

Insérer un séparateur

Syntaxe

---

Rendu

Les notes de bas de page

Les notes de bas de page permettent d’ajouter une précision sans alourdir le texte principal. Chaque note est associée à un identifiant placé entre [^ et ].

Syntaxe

Une note peut être numérotée[^1].
Elle peut aussi avoir un nom[^details].

[^1]: Une précision courte.
[^details]: Une explication plus complète avec un
    [lien vers Composed](https://composed.fr).

Rendu

Une note peut être numérotée¹. Elle peut aussi avoir un nom².

Sélectionnez le numéro en exposant pour accéder à la note. Les notes sont regroupées à la fin de l’article et comportent un lien de retour.

En résumé

Markdown est un langage simple, léger et rapide à prendre en main. En quelques caractères seulement, il permet de créer des documents bien structurés, faciles à lire et compatibles avec de nombreux outils.

Les exemples présentés dans ce guide couvrent les fonctionnalités essentielles que vous utiliserez au quotidien. Une fois ces bases maîtrisées, vous pourrez découvrir les fonctionnalités avancées comme les diagrammes Mermaid, les alertes GitHub ou encore l’intégration de HTML dans Markdown.