Aide-mémoire Markdown : Guide complet de la syntaxe

· 12 min de lecture

Table des matières

Qu'est-ce que Markdown ?

Markdown est un langage de balisage léger créé par John Gruber et Aaron Swartz en 2004 qui a révolutionné notre façon d'écrire pour le web. Il vous permet de formater du texte brut en utilisant une syntaxe simple et intuitive qui est à la fois lisible par l'humain et analysable par la machine.

Contrairement au HTML, qui nécessite des balises verbeuses et des éléments de fermeture, Markdown utilise des symboles naturels comme les astérisques, les dièses et les crochets. Cela rend l'écriture plus rapide et le texte source lisible même sans rendu. Un document Markdown semble propre et logique dans sa forme brute, c'est pourquoi il est devenu la norme universelle pour la documentation technique.

La philosophie derrière Markdown est simple : l'écriture doit être facile, et la syntaxe doit être invisible. Lorsque vous lisez un fichier Markdown, vous lisez d'abord le contenu, le balisage ensuite. C'est fondamentalement différent des langages de balisage traditionnels où les balises obscurcissent souvent le contenu réel.

Où Markdown est utilisé

Markdown est devenu omniprésent dans l'écosystème technologique et au-delà :

Besoin de convertir votre Markdown en HTML pour la publication web ? Essayez notre convertisseur Markdown vers HTML pour une conversion instantanée et précise.

Conseil pro : Les fichiers Markdown utilisent l'extension .md ou .markdown. La plupart des plateformes reconnaissent les deux, mais .md est plus courant et concis.

Titres et structure du document

Les titres sont l'épine dorsale de la structure du document en Markdown. Ils créent une hiérarchie, améliorent la lisibilité et aident à la fois les humains et les moteurs de recherche à comprendre l'organisation de votre contenu.

Syntaxe de base des titres

Markdown prend en charge six niveaux de titres en utilisant des symboles dièse (#). Le nombre de dièses détermine le niveau du titre :

# Titre 1 (H1)
## Titre 2 (H2)
### Titre 3 (H3)
#### Titre 4 (H4)
##### Titre 5 (H5)
###### Titre 6 (H6)

Chaque niveau de titre a une signification sémantique. H1 est le titre de votre document, les H2 sont les sections principales, les H3 sont les sous-sections, et ainsi de suite. Cette hiérarchie est cruciale pour l'accessibilité et le référencement.

Syntaxe alternative pour H1 et H2

Markdown prend également en charge une syntaxe alternative de « soulignement » pour les titres H1 et H2 :

Titre 1
=========

Titre 2
---------

Bien que cette syntaxe soit valide, la syntaxe avec dièse est plus courante et prend en charge les six niveaux de titres. La plupart des développeurs préfèrent la cohérence de l'utilisation des dièses dans leurs documents.

Bonnes pratiques pour les titres

Astuce rapide : De nombreux analyseurs Markdown génèrent automatiquement des liens d'ancrage à partir des titres, convertissant « Débuter » en #débuter. Cela permet des liens profonds vers des sections spécifiques.

Formatage de texte et emphase

Markdown fournit une syntaxe intuitive pour les besoins courants de formatage de texte. Ces options de formatage fonctionnent en ligne dans les paragraphes et peuvent être combinées pour un style plus complexe.

Texte gras et italique

L'emphase est créée en utilisant des astérisques ou des traits de soulignement :

**Texte gras** ou __Texte gras__
*Texte italique* ou _Texte italique_
***Gras et italique*** ou ___Gras et italique___

Les astérisques et les traits de soulignement fonctionnent de manière identique, mais les astérisques sont plus courants. Choisissez un style et respectez-le pour la cohérence. De nombreux guides de style recommandent les astérisques car ils sont plus faciles à taper et plus visuellement distincts.

Barré et autres formatages

Les options de formatage supplémentaires incluent :

~~Texte barré~~
`Code en ligne`
==Texte surligné== (certains analyseurs)
X^2^ (exposant, certains analyseurs)
H~2~O (indice, certains analyseurs)

Notez que le texte surligné, l'exposant et l'indice sont des extensions non prises en charge par tous les analyseurs Markdown. GitHub Flavored Markdown (GFM) prend en charge le barré mais pas le surlignage par défaut.

Citations

Les citations sont créées en utilisant le symbole supérieur à (>) :

> Ceci est une citation.
> Elle peut s'étendre sur plusieurs lignes.

>> Les citations imbriquées sont également possibles.
>> Ajoutez simplement plus de symboles >.

Les citations sont parfaites pour les citations, les extraits ou la mise en évidence d'informations importantes. Elles peuvent contenir d'autres formatages Markdown, y compris des titres, des listes et des blocs de code.

Règles horizontales

Créez des ruptures visuelles dans votre contenu avec des règles horizontales :

---
***
___

Les trois syntaxes produisent le même résultat. Utilisez trois traits d'union, astérisques ou traits de soulignement ou plus sur leur propre ligne. La plupart des développeurs préfèrent les traits d'union (---) pour plus de clarté.

Échapper les caractères spéciaux

Pour afficher des caractères Markdown littéraux, échappez-les avec une barre oblique inverse :

\*Pas italique\*
\# Pas un titre
\[Pas un lien\]

Ceci est essentiel lorsque vous devez montrer la syntaxe Markdown elle-même, comme dans la documentation ou les tutoriels.

Conseil pro : Lorsque vous écrivez sur du code ou des sujets techniques, utilisez le formatage de code en ligne (`backticks`) pour les noms de fonctions, les variables, les chemins de fichiers et les commandes. Cela améliore la lisibilité et aide les lecteurs à distinguer le code de la prose.

Les liens et les images utilisent une syntaxe similaire en Markdown, ce qui les rend faciles à mémoriser et à utiliser. Les deux prennent en charge les formats en ligne et de style référence pour différents cas d'utilisation.

Créer des liens

La syntaxe de base des liens est simple :

[Texte du lien](https://example.com)
[Lien avec titre](https://example.com "Texte au survol")

Le texte du lien apparaît entre crochets, suivi immédiatement de l'URL entre parenthèses. L'attribut de titre optionnel apparaît entre guillemets après l'URL et s'affiche au survol.

Liens de style référence

Pour les documents avec de nombreux liens répétés, les liens de style référence gardent votre contenu plus propre :

[Texte du lien][reference-id]
[Autre lien][reference-id]

[reference-id]: https://example.com "Titre optionnel"

Cette approche sépare les définitions de liens du contenu, rendant la source plus lisible. Elle est particulièrement utile dans les longs documents ou lorsque la même URL apparaît plusieurs fois.

Liens automatiques

Les URL et les adresses e-mail peuvent être automatiquement converties en liens :

<https://example.com>
<[email protected]>

De nombreux analyseurs Markdown créent également automatiquement des liens pour les URL nues sans chevrons, mais ce comportement n'est pas universel. L'utilisation de chevrons garantit un comportement cohérent sur toutes les plateformes.

Ajouter des images

La syntaxe des images est presque identique aux liens, avec un préfixe de point d'exclamation :

![Texte alternatif](image.jpg)
![Texte alternatif](image.jpg "Titre de l'image")
![Texte alternatif][image-reference]

[image-reference]: image.jpg "Titre optionnel"

Le texte alternatif est crucial pour l'accessibilité et le référencement. Il décrit l'image pour les lecteurs d'écran et apparaît si l'image ne se charge pas. Fournissez toujours un texte alternatif significatif qui décrit le contenu et le contexte de l'image.

Dimensionnement et alignement des images

Le Markdown standard ne prend pas en charge le dimensionnement ou l'alignement des images. Vous devrez utiliser du HTML pour ces fonctionnalités :

<img src="image.jpg" alt="Texte alternatif" width="300">
<img src="image.jpg" alt="Texte alternatif" style="float:right;margin:10px">

La plupart des analyseurs Markdown autorisent le HTML en ligne, ce qui en fait une solution pratique lorsque vous avez besoin de plus de contrôle sur la présentation des images.

Astuce rapide : Lors de la création de liens vers des pages internes, utilisez des URL relatives (/about/) au lieu d'URL absolues (https://example.com/about/). Cela rend votre contenu portable et fonctionne correctement dans les environnements de développement.

Listes : ordonnées, non ordonnées et listes de tâches

Les listes sont fondamentales pour organiser les informations en Markdown. Elles sont simples à créer et prennent en charge l'imbrication pour des hiérarchies complexes.

Listes non ordonnées

Créez des listes à puces en utilisant des astérisques, des traits d'union ou des signes plus :

* Élément un
* Élément deux
* Élément trois

- Élément un
- Élément deux
- Élément trois

+ Élément un
+ Élément deux
+ Élément trois

Les trois symboles fonctionnent de manière identique. Choisissez-en un et utilisez-le de manière cohérente dans votre document. La plupart des développeurs préfèrent les traits d'union pour leur clarté visuelle.

Listes ordonnées

Les listes numérotées utilisent des chiffres suivis de points :

1. Premier élément
2. Deuxième élément
3. Troisième élément

Voici une fonctionnalité utile : les chiffres réels n'ont pas d'importance. Markdown renumérotera automatiquement votre liste lors du rendu :

1. Premier élément
1. Deuxième élément
1. Troisième élément

Cela facilite la réorganisation des éléments car vous n'avez pas besoin de tout renuméroter manuellement. Cependant, commencer par 1. pour chaque élément peut être déroutant lors de la lecture de la source.

Listes imbriquées

Créez des listes hiérarchiques en indentant les éléments avec des espaces ou des tabulations :

1. Premier élément
   - Puce imbriquée
   - Autre puce imbriquée
2. Deuxième élément
   1. Numéro imbriqué
   2. Autre numéro imbriqué
      - Imbrication encore plus profonde

Utilisez une indentation cohérente (généralement 2 à 4 espaces) pour chaque niveau d'imbrication. La plupart des analyseurs sont flexibles, mais la cohérence améliore la lisibilité.

Listes de tâches

GitHub Flavored Markdown a introduit des listes de tâches pour suivre les tâches à faire :

- [ ] Tâche non cochée
- [x] Tâche cochée
- [ ] Autre tâche non cochée

Les listes de tâches sont interactives sur des plateformes comme GitHub — vous pouvez cocher et décocher les éléments directement dans la vue rendue. Elles sont parfaites pour la planification de projet, le suivi des problèmes et les documents collaboratifs.

Bonnes pratiques pour les listes

Code et blocs de code

Markdown excelle dans l'affichage du code, ce qui en fait le format préféré pour la documentation technique et les tutoriels de programmation.

Code en ligne

Enveloppez le code en ligne avec des backticks simples :

Utilisez la fonction `console.log()` pour déboguer.
L'élément `<div>` est un conteneur.

Le formatage du code en ligne préserve l'espacement et empêche l'interprétation Markdown. Il est essentiel pour mentionner des éléments de code dans les phrases.

Blocs de code

Créez des blocs de code en utilisant des triples backticks (blocs de code clôturés) :

```
function hello() {
  console.log("Bonjour, monde !");
}
```

C'est la syntaxe moderne et préférée. Elle est plus propre et plus flexible que l'ancienne méthode d'indentation (4 espaces ou 1 tabulation).

Coloration syntaxique

Spécifiez le langage de programmation après les backticks d'ouverture pour la coloration syntaxique :

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

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

```css
.container {
  max-width: 1200px;
  margin: 0 auto;
}
```

La plupart des analyseurs Markdown prennent en charge des dizaines de langages. Les identifiants courants incluent

We use cookies for analytics. By continuing, you agree to our Privacy Policy.