Vérification automatisée de la syntaxe Markdown (linter)#
Parmi ses nombreux atouts, la syntaxe Markdown doit probablement sa forte adoption à sa simplicité d'utilisation et à sa flexibilité. Sur un site, tel Geotribu, ouvert aux 4 vents de la contribution c'est à la fois une force et un élément à gérer car les erreurs de syntaxe, a priori inoffensives, peuvent mener à une page mal formée ou pire à casser le site... bon ok ce dernier scénario est peu probable mais un peu drama c'est toujours bien pour mettre la pression .
Pour vérifier la syntaxe et le respect des règles de rédaction définies, on utilise donc un linter dédié au Markdown : markdownlint-cli.
Utilisation de markdownlint(-cli)#
En local#
Pour utiliser l'outil, il faut disposer d'un interpréteur NodeJS :
1 2 3 4 5 6 7 8 |
|
Il est aussi possible d'utiliser markdownlint sous forme d'extension dans Visual Studio Code et probablement dans d'autres IDE.
Git hook#
Le linter est aussi configuré comme crochet git (voir la page dédiée) via pre-commit. Cela présente plusieurs avantages :
- pas besoin d'installer NodeJS, pre-commit s'occupe de tout dans un environnement dédié
- ça repère les erreurs voire les corrige automatiquement lors du commit
On peut donc l'utiliser ainsi :
1 2 3 4 5 |
|
Exécution automatisée sur la CI#
Etant donné que la très grande majorité des contributeur/ices n'utilisent pas l'édition locale ou n'installent pas les git hooks, la vérification syntaxique est automatiquement appliquée sur chaque commit publié sur GitHub dans une Pull Request.
Gérer les faux positifs du linter#
Le linter est un outil. Il peut donc faire des erreurs et signaler des faux-positifs ou se tromper sur des cas particuliers. On peut alors utiliser un commentaire pour désactiver certains contrôles sur certaines parties d'une page.
Désactiver une ou plusieurs règles avec leur code :
1 |
|
(Ré)activer une ou plusieurs règles dans une page :
1 |
|