Prosaprüfung mit Vale
Vale ist ein Kommandozeilen-Prose-Linter, der Ihre Dokumentation anhand konfigurierbarer Stilregeln überprüft. Er integriert sich gut mit Markdown- und MDX-Dateien und ist damit eine natürliche Ergänzung für docStatic-Projekte.
Vale installieren
Informationen zu Ihrer Plattform finden Sie in der Vale-Installationsanleitung. Vale ist über Homebrew, apt, Chocolatey und direkten Binär-Download verfügbar.
- macOS
- Linux
- Windows
brew install vale
# Debian / Ubuntu
sudo apt install vale
choco install vale
Projektkonfiguration
docStatic-Projekte enthalten eine .vale.ini im Repository-Stammverzeichnis. Die wichtigsten Einstellungen sind:
| Einstellung | Wert | Zweck |
|---|---|---|
StylesPath | .vale/styles | Verzeichnis für heruntergeladene und benutzerdefinierte Stilpakete |
MinAlertLevel | suggestion | Alle Ergebnisse anzeigen (Vorschlag, Warnung, Fehler) |
[formats] | mdx = md | .mdx-Dateien als Markdown behandeln |
Stile synchronisieren
Nach dem Klonen des Repos führen Sie einmalig vale sync aus, um die in .vale.ini aufgelisteten Stilpakete herunterzuladen:
vale sync
Dadurch wird .vale/styles/ mit den konfigurierten Paketen befüllt. Fügen Sie .vale/styles/ zu .gitignore hinzu, damit heruntergeladene Pakete nicht gespeichert werden.
Dokumentation prüfen
Vale gegen das Verzeichnis docs/ ausführen:
vale docs/
Oder eine einzelne Datei prüfen:
vale docs/guides/my-page.mdx
Vale gibt Ergebnisse nach Datei gruppiert aus, mit Zeilennummer, Warnstufe und der ausgelösten Regel.
Stilpakete hinzufügen
Vale verfügt über eine Bibliothek von Community-Stilpaketen (Google, Microsoft, write-good und weitere). Um eines hinzuzufügen, referenzieren Sie es in .vale.ini unter BasedOnStyles:
[*.{md,mdx}]
BasedOnStyles = Vale, Google
Dann führen Sie erneut vale sync aus, um es herunterzuladen.
Sie können projektspezifische Regeln als YAML-Dateien in .vale/styles/ hinzufügen. Siehe die Vale-Dokumentation für das Regelformat.
Editor-Integration
Vale verfügt über Erweiterungen für VS Code (Vale VSCode) und andere Editoren, die Ergebnisse inline anzeigen, während Sie schreiben.