Markdown linter - corriger les problèmes de formatage dans les fichiers md

Vous écrivez des fichiers Markdown .md (et vous avez bien raison) et vous voulez juste vérifier (et corriger automatiquement) quelques problèmes comme plusieurs lignes vides d'affilée, un mélange de types de puces (- et * dans le même document), un titre # suivi d'un ### (autrement dit, vous avez oublié le niveau ##) et bien d'autres.

Il existe un outil pour ça : Markdown lint et une image Docker peterdavehello/markdownlint.

Voyons comment l'utiliser.

Comme tout linter, il est surtout utile quand vous n'avez plus à y penser : Git - pre-commit-hooks liste un hook markdownlint qui s'exécute à chaque commit.

En lançant docker run --rm -v .:/md peterdavehello/markdownlint markdownlint ., vous scannez votre dossier courant (récursivement), à la recherche de tous les fichiers Markdown, et vous obtenez la liste des erreurs éventuelles.

Et la liste peut être énorme si vous utilisez des dépendances comme, pour PHP, le dossier vendor ou node_modules pour npm/yarn. Il suffit de les ignorer.

Ignorer certains fichiers/dossiers​

Créez un fichier appelé .markdownlint_ignore à la racine de votre projet avec ce contenu :

node_modules/**/*.markdown
node_modules/**/*.md
vendor/**/*.markdown
vendor/**/*.md

Cette fois, lancez docker run --rm -v .:/md peterdavehello/markdownlint markdownlint --ignore-path .markdownlint_ignore ..

La liste sera probablement plus courte et ne contiendra que vos fichiers.

Ignorer certaines erreurs​

Vous pouvez ignorer certaines erreurs détectées, comme l'utilisation de HTML inline, en créant un fichier appelé .markdownlint.json. Vous trouverez un exemple sur https://github.com/DavidAnson/markdownlint/blob/main/.markdownlint.json. Voir https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md pour plus d'informations.

Pour utiliser votre fichier de configuration, lancez maintenant docker run --rm -v .:/md peterdavehello/markdownlint markdownlint --config .markdownlint.json --ignore-path .markdownlint_ignore ..

Certaines erreurs peuvent être corrigées automagiquement​

Certaines erreurs peuvent être corrigées automagiquement, comme les lignes vides multiples ou les espaces superflus en fin de ligne.

Le flag ici est --fix mais attention : puisque les corrections modifient les fichiers, vous devez aussi ajouter le flag --user $(id -u):$(id -g) pour que les fichiers soient mis à jour tout en restant votre propriété.

On assemble le tout​

L'instruction finale devient : docker run --rm --user $(id -u):$(id -g) -v .:/md peterdavehello/markdownlint markdownlint --fix --config .markdownlint.json --ignore-path .markdownlint_ignore . et c'est celle que je lance chaque fois que je publie sur ce blog.

Se simplifier la vie​

Vous n'avez évidemment pas besoin de retenir la commande entière. Avec un Makefile dans votre projet, vous pouvez créer un nouveau target qui contient la commande.

Pour ce blog par exemple, je lance make lint dans mon processus de déploiement. Vous pouvez le voir ici.