markdown linting accessibility guide de style documentation

Guide du linting Markdown : 15 problèmes courants et leurs solutions

Recherchez et corrigez les problèmes courants de Markdown, notamment les titres ignorés, le texte alternatif d'image manquant, les URL nues, les barrières de code brisées, les listes incohérentes et les tableaux mal formés.

W
WordToMD Équipe
·

Markdown est permissif.Un document comportant des erreurs structurelles peut toujours s'afficher, ce qui rend ces erreurs faciles à manquer jusqu'à ce qu'un tableau se brise, qu'un en-tête disparaisse de la navigation ou qu'une image n'ait plus de sens pour un utilisateur de lecteur d'écran.

Markdown le linting est le processus de vérification du texte source pour détecter les problèmes de structure, d'accessibilité et de cohérence avant la publication.Commencez par le Linter Markdown pour détecter les niveaux de titre ignorés, le texte alternatif d'image manquant, les URL nues, les clôtures de code sans étiquette ou non fermées et les espaces de fin.Utilisez ensuite la liste de contrôle manuelle de ce guide pour une révision éditoriale plus large.

Linting ne consiste pas à appliquer des préférences arbitraires.Une règle utile devrait éviter un réel problème de lecture, de rendu, de maintenance ou d’accessibilité.

Liste de contrôle rapide de pré-publication

VérifierPourquoi c'est importantAutomatisé ou manuel ?
Hiérarchie des titresPréserve la structure du documentLinter
Texte alternatif de l'imageRend les images compréhensibles sans la vueLinter
Liens descriptifsAméliore l'accessibilité et la numérisationLinter + révision manuelle
Clôtures à code ferméesEmpêche le reste de la page de devenir du codeLinter
Étiquettes de langue du codePermet une coloration syntaxique utileLinter
Espaces de finÉvite les comportements invisibles spécifiques au dialecteLinter
Un titre de page clairMaintient l'objectif de la page sans ambiguïtéRévision manuelle
Listes cohérentesEmpêche les imbrications briséesRévision manuelle
Tableaux validesMaintient la structure de la colonne intacteRévision manuelle
Rubriques uniquesEmpêche la confusion des ancres en doubleRévision manuelle
Utilisation portable HTMLÉvite les échecs spécifiques au moteur de renduRévision manuelle
Paragraphes lisiblesAméliore la compréhensionRévision manuelle

Collez un document représentatif dans le linter, exécutez les vérifications, corrigez les lignes signalées, puis prévisualisez la page complète dans son système de publication actuel.

1. Niveaux de titres ignorés

Problème

# Deployment Guide

### Configure credentials

Le document passe de H1 à H3.Cela peut sembler acceptable lorsque la taille des polices est le seul signal visible, mais il manque un niveau dans le contour structurel.

Correction

# Deployment Guide

## Configure credentials

Utilisez des titres pour décrire la hiérarchie, et non pour choisir une taille visuelle.Si « Configurer les informations d'identification » appartient réellement à une section manquante, ajoutez cette section :

# Deployment Guide

## Preparation

### Configure credentials

Le Linter Markdown signale un titre qui saute de plus d'un niveau.

2. Rubriques H1 multiples ou manquantes

Une page doit normalement avoir un titre clair.Certains systèmes de documentation génèrent le H1 à partir de la première partie, tandis que d'autres l'attendent dans le corps Markdown.Sachez quelle convention votre site utilise.

Source ambiguë

# Installation

# Configuration

Effacer la source

# Product setup

## Installation

## Configuration

Si votre modèle de site affiche title: Product setup comme la page H1, le corps peut commencer par H2 à la place.La règle n'est pas « chaque fichier Markdown doit contenir exactement un #.” The rule is “the rendered page needs one unambiguous primary heading.”

3. Titres utilisés uniquement à des fins d'accentuation

Cette source crée une entrée de plan inutile :

#### Important!

Si le texte n'introduit pas de section, utilisez de la prose ou une légende appropriée :

**Important:** Back up the database before continuing.

Les titres doivent aider les lecteurs à naviguer.Les titres décoratifs rendent la table des matières bruyante et réduisent l'utilité de la navigation assistée.

4. Images sans texte alternatif

Problème

![](architecture.png)

L'image n'a pas d'alternative textuelle.Un lecteur qui ne peut pas le voir ne reçoit aucune explication, et quelqu'un qui parcourt des images cassées ou désactivées ne peut pas déterminer son objectif.

Correction

![Request flow from the browser through the API gateway to the orders service](architecture.png)

Décrivez les informations apportées par l'image, pas seulement son apparence.Évitez les expressions telles que « image de » à moins que le support ne soit important.

Les images décoratives constituent un cas particulier.Un texte alternatif vide peut être correct dans HTML lorsqu'une image ne transmet aucune information, mais les moteurs de rendu Markdown et les flux de travail de contenu diffèrent.Si une image est purement décorative, demandez d’abord si elle a sa place dans la documentation technique.

Le linter signale les images Markdown avec un texte alternatif vide.Le Formateur d’images peut générer un balisage d'image avec une légende alternative explicite et facultative.

Problème

Visit https://example.com/docs/setup for more information.

Les URL nues sont difficiles à analyser et peuvent être désagréables lorsqu'elles sont lues à haute voix.Le texte du lien générique n’est pas beaucoup mieux :

[Click here](https://example.com/docs/setup).

Correction

Read the [service setup guide](https://example.com/docs/setup).

Les liens descriptifs indiquent aux lecteurs ce qu'ils vont ouvrir.Ils restent également significatifs lorsqu'ils sont extraits dans une liste de liens.

Le linter identifie de nombreux nus http:// and https:// URL, mais une révision éditoriale est toujours nécessaire pour juger si le texte du lien est utile.

6. Clôtures à code non fermées

Problème

```javascript
const status = 'ready';

## Next section

Sans clôture de fermeture, le moteur de rendu peut traiter le reste de la page comme du code.

Correction

```javascript
const status = 'ready';
```

## Next section

Une clôture non fermée peut briser une grande partie d'un document par ailleurs valide.Le linter indique la ligne où commence la clôture inégalée.

7. Clôtures de code sans identifiants linguistiques

Moins utile

```
npm run build
```

Mieux

```bash
npm run build
```

Un identifiant de langue permet la coloration syntaxique et communique le type de contenu que le lecteur voit.Utilisez des identifiants courants tels que javascript, typescript, json, html, css, bash, powershell, yaml, ou markdown.

N'ajoutez pas un langage inexact simplement pour obtenir des couleurs.Pour une sortie non structurée, utilisez text lorsque la destination le reconnaît.

8. Indentation de liste incohérente

Problème

- Install dependencies
    - Production packages
  * Development packages
	- Optional tools

Les onglets, espaces et marqueurs mixtes sont difficiles à examiner et peuvent s'afficher à différents niveaux.

Correction

- Install dependencies
  - Production packages
  - Development packages
  - Optional tools

Choisissez une largeur d'indentation cohérente pour le projet.Le nombre exact d'espaces peut dépendre du dialecte Markdown et du contenu de la liste, mais la cohérence est essentielle.

Utilisez le Formateur de listes imbriquées pour normaliser les puces mixtes, la numérotation, les onglets et l'indentation avant l'examen final.

9. Séquences de numéros saisies manuellement

Les longues listes numérotées sont coûteuses à maintenir :

1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.

De nombreux moteurs de rendu Markdown permettent à chaque élément d'utiliser 1. tout en affichant toujours une séquence ordonnée :

1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.

Cela réduit le bruit de renumérotation dans les différences de source.Cependant, il est plus facile de discuter d’une source explicitement numérotée lorsque les instructions font référence à « l’étape 3 ».Choisissez une convention de projet et appliquez-la de manière cohérente.

Ne combinez pas de chiffres saisis, de marqueurs de liste ordonnée et de texte de paragraphe.Confirmez le résultat rendu après avoir modifié les étapes imbriquées.

10. Tableaux mal formés

Problème

| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |

Les lignes de séparateur et de données ne contiennent pas le même nombre logique de colonnes.

Correction

| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |

Vérifiez également les caractères de barre verticale non échappés à l'intérieur des cellules :

| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |

Le Formateur de tableaux Markdown aide à exposer les lignes inégales et produit une source alignée.Pour créer visuellement un nouveau tableau, utilisez le Markdown Générateur de table.

11. Titres en double et collisions d'ancres

Un document peut légitimement répéter un titre visible tel que « Exemples », mais les identifiants d'ancrage générés automatiquement peuvent devenir #examples, #examples-1, et #examples-2.La règle exacte varie selon le moteur de rendu.

Les titres répétés fragilisent les liens manuels :

- [API examples](#examples)
- [CLI examples](#examples)

Préférer les rubriques descriptives :

## API examples

## CLI examples

Générez ensuite une table des matières avec le Markdown Générateur COT et vérifier les ancrages dans la plateforme cible.

12. Espaces de fin

Les espaces en fin de ligne sont invisibles.Dans certains dialectes Markdown, deux espaces de fin créent un saut de ligne dur, ce qui signifie qu'une action accidentelle de l'éditeur peut modifier le rendu.

Le linter signale les espaces de fin afin que vous puissiez décider si c'est délibéré.Préférez une ligne vide pour la séparation des paragraphes.Si un saut de ligne définitif est véritablement nécessaire, documentez et appliquez la convention choisie pour le projet de manière cohérente.

Les éditeurs peuvent généralement supprimer automatiquement les espaces de fin lors de l'enregistrement, mais vérifiez que cela ne modifie pas les sauts de ligne intentionnels dans le contenu existant.

13. Brut HTML qui réduit la portabilité

Markdown permet souvent d'embarquer HTML :

<div class="warning-panel">
  Restarting the service ends active sessions.
</div>

Ce bloc peut fonctionner sur un site Web et être échappé, nettoyé ou stylisé de manière incorrecte ailleurs.Préférer le portable Markdown quand il peut exprimer la même signification :

> **Warning:** Restarting the service ends active sessions.

Utilisez délibérément HTML pour des fonctionnalités que Markdown ne peut pas exprimer, telles que le dimensionnement contrôlé de l'image ou une prise en charge <details> .Conservez une liste des destinations où le contenu doit être restitué et testez chacune d'entre elles.

Le Générateur de légende peut produire une syntaxe spécifique à la plate-forme pour GitHub, Obsidian et MkDocs lorsque la portabilité est moins importante que la présentation native.

14. Paragraphes trop longs et mauvaise numérisation

Markdown peut être structurellement valide et néanmoins difficile à lire.Un mur de texte contenant plusieurs décisions, avertissements et procédures devrait être réorganisé.

Utilisation :

  • de courts paragraphes pour une idée principale ;
  • rubriques descriptives pour la navigation ;
  • listes d'éléments parallèles ;
  • pour les champs véritablement comparables ;
  • pour l'entrée et la sortie littérales ;
  • légendes pour un petit nombre d'exceptions importantes.

Ne transformez pas chaque phrase en puce.Les listes fonctionnent mieux lorsque les éléments ont le même rôle grammatical et conceptuel.

Utilisation Nombre de mots et temps de lecture pour inspecter le nombre de paragraphes, le nombre de titres et la longueur de lecture, mais traiter les statistiques comme des signaux plutôt que comme des cibles.

15. Syntaxe spécifique au moteur de rendu sans plan de compatibilité

Les listes de tâches GitHub, les liens wiki Obsidian, les avertissements MkDocs, les notes de bas de page, les listes de définitions et les documents préliminaires sont tous utiles, mais ils ne sont pas pris en charge de la même manière partout.

À titre d'exemple:

> [!NOTE]
> This callout is useful in destinations that recognize the syntax.

Avant d'adopter une extension, répondez à trois questions :

  1. Quel moteur de rendu possède la sortie finale ?
  2. Le contenu doit-il être déplacé ailleurs ultérieurement ?
  3. Que verront les lecteurs lorsque l'extension n'est pas prise en charge ?

Conservez une base Markdown portable et ajoutez une syntaxe de plate-forme à la périphérie de la publication lorsque cela est possible.

Un flux de travail pratique pour le peluchage

Étape 1 : Vérifier la structure

Collez la source dans le Linter Markdown.Corrigez d'abord les erreurs, puis les avertissements, puis les éléments de cohérence des informations.Les contrôles automatisés doivent identifier les emplacements ;ils ne devraient pas réécrire silencieusement le sens.

Étape 2 : Normaliser les éléments difficiles

Utiliser des outils ciblés pour le nettoyage mécanique :

Les modifications ciblées produisent des différences plus petites et plus faciles à réviser qu'un formateur large qui réécrit l'intégralité du fichier.

Étape 3 : Prévisualiser le document

Ouvrir la source dans le Markdown Editeur et comparez le Markdown avec la sortie rendue.Vérifiez :

  • titres et table des matières ;
  • listes et listes de tâches ;
  • tableaux sur écran étroit ;
  • images et liens ;
  • et code en ligne ;
  • légendes ou brut HTML.

Étape 4 : Tester la destination réelle

Un aperçu générique ne peut pas reproduire tous les moteurs de rendu.Ouvrez le fichier dans GitHub, Obsidian, GitLab, MkDocs ou sur le site de documentation actuel avant de le publier.

Étape 5 : Réviser le sens, pas seulement la syntaxe

Aucun linter ne peut déterminer si une procédure est sûre, si un lien pointe vers la politique prévue ou si une description d'image communique la conclusion importante.Un évaluateur humain doit confirmer l’exactitude, l’exhaustivité, le ton et l’adéquation au public.

Recommandations du guide de style d'équipe

Une courte convention documentée est plus efficace que des dizaines de préférences tacites.Définir :

  • si le titre de la page figure en avant-plan ou dans le corps du Markdown ;
  • la progression de cap autorisée ;
  • indentation de liste et style de liste ordonnée ;
  • Exigences linguistiques du code-clôture ;
  • comment les images et le texte alternatif sont examinés ;
  • limites de complexité des tables ;
  • autorisait HTML et extensions de plateforme ;
  • longueur maximale de la ligne, si l'équipe en utilise une ;
  • comment les liens sont vérifiés ;
  • quelles règles linter bloquent la publication.

Commencez par des règles qui évitent les défauts réels.Ajoutez une règle uniquement lorsque l'équipe comprend le problème qu'elle résout.

FAQ

Les Markdown valides sont-ils automatiquement accessibles ?

Non. Une syntaxe valide peut toujours contenir du texte alternatif vide, des liens vagues, des titres déroutants, des diagrammes inaccessibles et un mauvais ordre de lecture.L’accessibilité nécessite une révision structurelle et éditoriale.

Le Markdown Linter va-t-il réécrire mon document ?

Le linter WordToMD signale des problèmes numérotés par ligne.Il ne réécrit pas silencieusement la source, vous conservez donc le contrôle de chaque correction.

Pourquoi le linter signale-t-il une URL nue ?

Le texte du lien descriptif est plus facile à numériser et plus utile à la technologie d'assistance.Remplacez l'URL par une étiquette significative, sauf si l'adresse littérale correspond aux informations dont les lecteurs ont besoin.

Une clôture de code sans étiquette est-elle toujours fausse ?

Pas toujours, mais un identifiant de langue correct améliore généralement la clarté et la coloration syntaxique.Utiliser text pour une sortie simple lorsqu'il est pris en charge au lieu d'attribuer un langage de programmation inexact.

Tous les projets doivent-ils utiliser les mêmes règles de peluchage ?

Non. Un GitHub README, un coffre-fort Obsidian, une référence API et un site de publication ont des conventions différentes.Partagez un ensemble de règles de base en matière de structure et d'accessibilité, puis ajoutez des contrôles spécifiques à la destination.

Le peluchage peut-il remplacer la relecture ?

Non. Un linter détecte les motifs.Il ne peut pas vérifier de manière fiable la vérité technique, la qualité des arguments, l’intention de l’utilisateur ou si une phrase est compréhensible dans son contexte.

Conclusion de l'enquête

Bon Markdown est plus que la source qui arrive à restituer.Il a un aperçu clair, des liens significatifs, des images accessibles, des barrières de code complètes, des listes cohérentes, des tableaux valides et une relation définie avec sa plateforme de publication.

Exécutez le Linter Markdown pour des contrôles structurels rapides, utilisez le Markdown Editeur pour un examen visuel et appliquez des formateurs ciblés uniquement là où ils facilitent la maintenance de la source.Le résultat est Markdown qui est plus portable, accessible et fiable dans les modifications futures.