Écrire du Markdown accessible (série complète)

Public visé : vous savez ce qu'est un fichier texte, vous n'avez jamais (ou peu) écrit de Markdown. À la fin, vous saurez rédiger une page complète — titres, listes, liens, images, code, tableaux — qui reste accessible une fois transformée en HTML.

Pourquoi « accessible » ? Le Markdown que vous écrivez devient du HTML. Ce HTML est lu à voix haute par les lecteurs d'écran, parcouru à la touche Tab, agrandi au zoom 200 %. Beaucoup de choix d'écriture (l'ordre des titres, le texte d'un lien, la description d'une image) décident si ces personnes peuvent vous lire. On apprend donc chaque brique en même temps que le réflexe d'accessibilité qui va avec.

Ce dont vous avez besoin

• Un éditeur de texte (n'importe lequel) et un fichier .md.
• Un moyen de voir le rendu : l'aperçu de votre éditeur, ou une plateforme qui affiche le Markdown. On s'appuie sur CommonMark (le socle standard) et sur ses extensions GFM (tableaux, cases à cocher, texte barré). C'est le dialecte le plus répandu.

Écrivez chaque exemple dans votre fichier, regardez le rendu, comparez. C'est un tutoriel : le chemin décrit ici fonctionne, suivez-le dans l'ordre.

Étape 1 — La structure : titres et paragraphes

Ouvrez votre fichier et tapez ceci :

# Guide de démarrage

## Installation

Un paragraphe se sépare du suivant par **une ligne vide**.

Deuxième paragraphe.

---

Texte après un séparateur horizontal.

Ce que vous venez de faire :

• # crée un titre de niveau 1, ## un niveau 2, jusqu'à ###### (niveau 6).
• Une ligne vide sépare deux paragraphes.
• --- (seul sur sa ligne) trace un séparateur horizontal.

Le réflexe accessibilité — la règle la plus importante du tutoriel : les titres forment le plan que les lecteurs d'écran utilisent pour naviguer dans la page (« aller au titre suivant »). Deux règles :

1. Un seul # (niveau 1) par document : c'est le titre de la page.
2. Ne sautez pas de niveau. Après un ##, le sous-titre est un ###, jamais un ####. Ne choisissez pas un niveau « parce que la police est plus jolie » : le niveau exprime la hiérarchie, pas la taille.

Un plan qui saute de # à #### est, pour un lecteur d'écran, une table des matières trouée.

Exercice — Écrivez une page avec un #, deux sections ## et un séparateur. Vérifiez dans l'aperçu que la hiérarchie descend sans trou.

Étape 2 — Mettre des mots en valeur

*italique* ou _italique_
**gras** ou __gras__
**_gras et italique_**
~~barré~~

• * ou _ autour d'un mot → italique.
• ** ou __ → gras.
• ~~ → barré (une extension GFM).

Le réflexe accessibilité : l'emphase visuelle n'est pas toujours annoncée par les lecteurs d'écran. Ne faites donc jamais porter une information par le seul gras ou la seule couleur. « Cliquez sur le bouton rouge » est inutilisable pour qui ne voit pas la couleur — écrivez « le bouton Enregistrer ». N'abusez pas non plus de l'emphase : trois mots en gras dans une phrase, et plus rien ne ressort.

Exercice — Mettez en forme une phrase avec de l'italique, du gras et du barré, sans qu'aucune information ne dépende uniquement du style.

Étape 3 — Les listes et les tâches

- Première puce
- Deuxième puce
  - Sous-puce (deux espaces d'indentation)

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

- [ ] Tâche à faire
- [x] Tâche faite

• - (ou *) commence une puce ; deux espaces d'indentation créent un sous-niveau.
• 1. 2. … : liste ordonnée (le rendu renumérote automatiquement).
• - [ ] et - [x] : cases à cocher (extension GFM).

Le réflexe accessibilité : utilisez une vraie liste Markdown, pas une suite de lignes commençant par un tiret « à la main » ou par « - » collé au texte. Le lecteur d'écran annonce « liste de 3 éléments » et permet d'y naviguer si c'est une vraie liste. Choisissez le bon type : ordonnée quand l'ordre compte (une procédure), non ordonnée sinon.

Exercice — Créez une checklist de trois tâches, dont une cochée, et une procédure numérotée de trois étapes.

Étape 4 — Les liens et les images (le cœur de l'accessibilité)

[Documentation](https://exemple.<VOTRE_DOMAINE>/docs)

Voir la [page de contact][contact] pour nous joindre.

![Diagramme du flux de commande : panier, paiement, confirmation](images/flux.png)

[contact]: https://exemple.<VOTRE_DOMAINE>/contact

• Lien inline : [texte affiché](url).
• Lien par référence : [texte][étiquette], et l'URL est définie plus bas ([étiquette]: url). Pratique quand la même URL revient souvent.
• Image : ![texte alternatif](chemin).

Le réflexe accessibilité — deux points à ne jamais rater :

1. Le libellé d'un lien doit avoir du sens hors contexte. Un lecteur d'écran peut lister « tous les liens de la page ». Une page pleine de « cliquez ici » ou « en savoir plus » devient inutilisable. Écrivez [Télécharger le rapport annuel](...), pas [cliquez ici](...).
2. Le texte alternatif d'une image (alt) est obligatoire et c'est lui que le lecteur d'écran lit à la place de l'image. Décrivez l'information portée par l'image, pas « image de… ». Deux cas :
   • Image porteuse de sens → décrivez-la : ![Courbe des ventes en hausse au 4e trimestre](...).
   • Image purement décorative → alt vide : ![](deco.png), pour que le lecteur d'écran l'ignore au lieu de lire un nom de fichier.

Préférez des URL stables et explicites.

Exercice — Ajoutez un lien de référence vers une autre page, et une image avec un alt qui décrit vraiment son contenu.

Étape 5 — Le code et les citations

Pour du code sur une ligne, entourez-le d'un backtick : `exemple`. Pour un bloc, entourez-le de trois backticks et indiquez le langage :

Voici du `code` au fil du texte.

```json
{ "actif": true }
```

> Une citation se marque avec un chevron.

• Bloc de code : ouvrez et fermez par ```, avec le nom du langage sur la ligne d'ouverture.
• Citation : > en début de ligne.
• Si votre code contient lui-même des backticks, ouvrez le bloc avec une clôture plus longue (quatre backticks).

Le réflexe accessibilité : préciser le langage (json, bash…) permet la coloration syntaxique et aide certains outils à annoncer la nature du bloc. Un bloc de code n'est pas un moyen de « faire joli » : ne l'utilisez que pour du vrai code ou des commandes.

Exercice — Ajoutez un bloc de code annoté json et une courte citation.

Étape 6 — Les tableaux

| Nom  | Rôle | Actif |
|:-----|:----:|------:|
| Ana  | Dev  | Oui   |
| Marc | Ops  | Non   |

• La première ligne = les en-têtes ; la deuxième = les tirets qui délimitent.
• Les : dans la ligne de tirets règlent l'alignement : à gauche (:---), centré (:--:), à droite (---:).

Le réflexe accessibilité : un tableau doit servir à présenter des données, jamais à mettre en page. La première ligne doit être une vraie ligne d'en-têtes : c'est elle qui permet à un lecteur d'écran d'annoncer, pour chaque cellule, « colonne Rôle : Dev ». Sans en-têtes, un tableau n'est qu'une grille muette. Gardez les cellules courtes et lisibles.

Note de rendu : c'est le générateur HTML qui associe correctement les en-têtes aux cellules. Votre part d'auteur, ici, est de toujours fournir une ligne d'en-têtes claire et de ne pas détourner le tableau à des fins de mise en page.

Exercice — Reprenez le tableau ci-dessus et ajoutez une colonne « Équipe ».

Étape 7 — Échapper des caractères et le piège du HTML

Parfois un caractère spécial doit s'afficher littéralement. Le \ (antislash) le protège :

\*ceci n'est pas de l'italique\*
\# ceci n'est pas un titre

Le Markdown tolère aussi du HTML inséré directement (<kbd>Ctrl</kbd>, <sup>2</sup>).

Le réflexe accessibilité — et de portabilité : restez en Markdown pur autant que possible. Le HTML inséré à la main est le premier endroit où l'accessibilité se casse (une balise ouverte sans être fermée, un titre <h4> posé au hasard qui brise la hiérarchie de l'étape 1, une image <img> sans alt). Le Markdown standard, lui, produit un HTML sémantique correct « gratuitement ». N'ouvrez la porte au HTML qu'en dernier recours, et dans ce cas appliquez les mêmes règles : hiérarchie des titres, alt sur les images, libellés de liens explicites.

Exercice — Dans une même phrase, échappez un * et un _ pour qu'ils s'affichent tels quels.

Étape 8 — Assembler un document complet et navigable

Vous avez toutes les briques. Voici comment structurer une page entière :

# Guide de l'API

## Sommaire
- [Introduction](#introduction)
- [Points d'accès](#points-dacces)
- [FAQ](#faq)

## Introduction
Texte d'introduction.

## Points d'accès
Liste des routes.

## FAQ
Questions fréquentes.

• Un # en tête, puis des sections ## dans un ordre logique.
• Un sommaire manuel (liste de liens vers les #ancres des titres) suffit pour un document court et aide grandement la navigation. Les ancres exactes dépendent de l'outil de rendu : vérifiez-les dans l'aperçu.

Le réflexe accessibilité — récapitulatif : un bon document accessible, c'est d'abord un document bien structuré. Reprenez chaque brique :

• Hiérarchie de titres continue, un seul #.
• Aucune information portée par le seul style ou la seule couleur.
• Vraies listes, bon type (ordonnée / non ordonnée).
• Libellés de liens explicites, alt pertinent sur chaque image.
• Blocs de code annotés d'un langage.
• Tableaux réservés aux données, avec ligne d'en-têtes.
• Markdown pur privilégié ; HTML manuel évité.

Exercice final — Rassemblez tout : rédigez une page d'une trentaine de lignes avec titre, sommaire, deux sections, une liste, un lien explicite, une image décrite, un bloc de code annoté et un petit tableau à en-têtes. Puis relisez-la avec la liste ci-dessus comme grille de contrôle.

Vérifier son travail

Écrire accessible, c'est bien ; le vérifier, c'est mieux. Deux niveaux :

• À la lecture : relisez avec la grille de l'étape 8. La plupart des défauts (titre sauté, alt manquant, « cliquez ici ») se repèrent à l'œil.
• Sur le rendu : si votre page devient une vraie page web, faites-la tester par un outil d'audit d'accessibilité automatisé, puis au clavier seul (Tab / Maj+Tab pour circuler entre les liens) et, si possible, avec un lecteur d'écran. L'automatique attrape le structurel ; l'humain attrape le sens.

Pour aller plus loin

• CommonMark — la spécification de référence : https://spec.commonmark.org/
• GFM — les extensions (tableaux, tâches, barré) : https://github.github.com/gfm/
• Les référentiels d'accessibilité web (type WCAG) pour approfondir la logique derrière chaque réflexe vu ici.