Correction de prose avec Vale

Vale est un linter de prose en ligne de commande qui vérifie votre documentation par rapport à des règles de style configurables. Il s'intègre bien avec les fichiers Markdown et MDX, ce qui en fait un outil naturellement adapté aux projets docStatic.

Installer Vale

Consultez le guide d'installation de Vale pour les instructions spécifiques à votre plateforme. Vale est disponible via Homebrew, apt, Chocolatey et en téléchargement direct de binaire.

macOS

brew install vale

Linux

# Debian / Ubuntu
sudo apt install vale

Windows

choco install vale

Configuration du projet

Les projets docStatic incluent un fichier .vale.ini à la racine du dépôt. Les paramètres clés sont :

Paramètre	Valeur	Objectif
StylesPath	.vale/styles	Répertoire pour les packages de styles téléchargés et personnalisés
MinAlertLevel	suggestion	Afficher tous les résultats (suggestion, avertissement, erreur)
[formats]	mdx = md	Traiter les fichiers .mdx comme du Markdown

Synchroniser les styles

Après avoir cloné le dépôt, exécutez vale sync une fois pour télécharger les packages de styles listés dans .vale.ini :

vale sync

Cela peuple .vale/styles/ avec les packages configurés. Ajoutez .vale/styles/ à .gitignore afin que les packages téléchargés ne soient pas validés.

Vérifier vos docs

Exécutez Vale sur le répertoire docs/ :

vale docs/

Ou vérifiez un seul fichier :

vale docs/guides/my-page.mdx

Vale affiche les résultats groupés par fichier, avec le numéro de ligne, le niveau d'alerte et la règle déclenchée.

Ajouter des packages de styles

Vale dispose d'une bibliothèque de packages de styles communautaires (Google, Microsoft, write-good, et d'autres). Pour en ajouter un, référencez-le dans .vale.ini sous BasedOnStyles :

[*.{md,mdx}]
BasedOnStyles = Vale, Google

Puis exécutez à nouveau vale sync pour le télécharger.

Règles personnalisées

Vous pouvez ajouter des règles spécifiques au projet sous forme de fichiers YAML dans .vale/styles/. Consultez la documentation Vale pour le format des règles.

Intégration dans l'éditeur

Vale dispose d'extensions pour VS Code (Vale VSCode) et d'autres éditeurs qui affichent les résultats en ligne pendant que vous écrivez.