Pourquoi écrire en Markdown
Markdown est un langage de balisage léger qui utilise des symboles simples pour représenter la mise en forme. Les rédacteurs n'ont pas besoin de quitter le clavier, se concentrent sur le contenu, et la mise en forme est générée automatiquement.
Avantages :
- Texte brut, ouvrable par n'importe quel éditeur
- Compatible avec le contrôle de versions (Git peut faire des diffs)
- Convertible en HTML, PDF, Word et autres formats
- Courbe d'apprentissage faible, prise en main en 10 minutes
Syntaxe de base
Titres
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
Il est recommandé de n'avoir qu'un seul titre de niveau 1 par article.
Paragraphes
Séparez les paragraphes par une ligne vide. Sans ligne vide, le contenu fait partie du même paragraphe.
Mise en valeur
**gras**
*italique*
~~barré~~
Listes
Non ordonnée :
- élément
- élément
- sous-élément (indenté)
Ordonnée :
1. Premier élément
2. Deuxième élément
Liens et images
[texte du lien](https://example.com)
Code
En ligne : code
Bloc de code :
```javascript
const x = 1;
### Citation
contenu de la citation deuxième ligne
### Ligne de séparation
## Syntaxe étendue
### Tableaux
| Nom | Âge |
|---|---|
| Tom | 25 |
### Liste de tâches
- Terminé
- Non terminé
### Notes de bas de page
Corps du texte[^1]
[^1]: explication de la note
### Barré
barré
### Liens automatiques
Les URL sont automatiquement converties en liens.
## Techniques d'écriture
### Hiérarchie des titres claire
- Titre de niveau 1 : titre de l'article
- Titre de niveau 2 : sections principales
- Titre de niveau 3 : sous-sections
- Ne pas sauter de niveaux (passer directement du niveau 1 au niveau 3)
### Paragraphes concis
- Un paragraphe, une idée
- Paragraphes pas trop longs (3 à 5 lignes idéalement)
- Remplacer les longs paragraphes par des listes
### Bien utiliser les listes
Pour le contenu parallèle, les listes sont plus claires que les paragraphes :
- Étapes : listes ordonnées
- Éléments parallèles : listes non ordonnées
- Comparaisons : tableaux
### Annoter la langue du code
Annotez la langue des blocs de code pour activer la coloration syntaxique :
Ajouter des descriptions aux images
La description dans  est importante :
- Affichée lorsque l'image ne se charge pas
- Lue par les lecteurs d'écran pour les utilisateurs malvoyants
- Bénéfique pour le SEO
Liens clairs
- Le texte du lien décrit la cible, évitez « cliquez ici »
- Liens externes : URL complète
- Liens internes : chemin relatif
Organisation de la documentation
Table des matières au début
Pour les longs documents, placez une table des matières au début avec des liens vers chaque section. Cela facilite la navigation.
Séparer les sections par des titres
Utilisez des titres pour séparer les sections, pas des lignes de séparation. Les titres ont une hiérarchie, les lignes de séparation n'en ont pas.
Séparer le code du texte
Laissez une ligne vide avant et après les blocs de code pour les détacher du texte. La lecture est plus claire.
Placer les images à bon escient
Placez les images juste après le texte concerné, ne les regroupez pas à la fin. Les lecteurs qui suivent l'ordre de lecture voient les images à temps.
Choix de l'éditeur
VS Code
- Gratuit et puissant
- Installer une extension Markdown (comme Markdown All in One)
- Aperçu en temps réel
- Adapté aux développeurs
Typora
- WYSIWYG (ce que vous voyez est ce que vous obtenez)
- Pas de fenêtre d'aperçu, édition directe du rendu
- Payant mais abordable
- Adapté à l'écriture concentrée
Obsidian
- Base de connaissances locale
- Liens bidirectionnels
- Riche en extensions
- Adapté aux notes et à la gestion des connaissances
Éditeurs en ligne
- StackEdit : éditeur Markdown en ligne
- JianShu : plateforme d'écriture en chinois
- Adapté à l'écriture occasionnelle
Convertir Markdown en HTML
Une fois le Markdown écrit pour un affichage web, convertissez-le en HTML. Utilisez l'outil Markdown vers HTML pour une conversion en un clic.
Erreurs courantes
Pas d'espace après le titre
#titre n'est pas reconnu, utilisez # titre (espace après #).
Indentation de liste incorrecte
Les sous-listes doivent être indentées de 2 ou 4 espaces (selon l'analyseur). Une indentation incorrecte empêche l'affichage des sous-listes.
Bloc de code non fermé
### Caractères spéciaux non échappés
Pour afficher des symboles comme * ou #, ajoutez \ devant pour les échapper : \* affiche *.
### Erreur de syntaxe de tableau
Un tableau doit comporter une ligne de séparation d'en-tête (| --- |). Sans elle, il n'est pas reconnu comme tableau.
### Parenthèses de lien déséquilibrées
`[lien](url` sans la parenthèse fermante, le lien n'est pas reconnu.
## Bonnes pratiques
### Un document, un sujet
Un article traite un sujet. Pour plusieurs sujets, divisez en plusieurs articles et reliez-les par des liens.
### Contenu d'abord, mise en forme ensuite
Rédigez d'abord le texte brut, puis ajoutez les balises Markdown. Évitez d'ajuster en écrivant, cela interrompt le fil de la pensée.
### Style unifié
L'équipe de rédaction unifie le style :
- Nombre de niveaux de titres
- Listes avec - ou *
- Langue d'annotation des blocs de code
- Profondeur maximale d'imbrication des listes
### Conserver le fichier source
Markdown est le fichier source, HTML/PDF sont des produits dérivés. Conservez le Markdown pour faciliter les modifications et régénérez les formats de sortie à chaque fois.
## Résumé
L'essentiel de la rédaction Markdown : hiérarchie des titres claire, paragraphes concis, bon usage des listes, code annoté avec sa langue, descriptions pour les images. Choisissez un éditeur adapté, unifiez le style et conservez le fichier source. Pour l'affichage, utilisez l'[outil DocsAll Markdown vers HTML](/convert-tools/markdown-to-html), exécuté côté navigateur.