Prose linting with Vale
Vale is a command-line prose linter that checks your documentation against configurable style rules. It integrates well with Markdown and MDX files, making it a natural fit for docStatic projects.
Install Vale
See the Vale installation guide for instructions for your platform. Vale is available via Homebrew, apt, Chocolatey, and direct binary download.
- macOS
- Linux
- Windows
brew install vale
# Debian / Ubuntu
sudo apt install vale
choco install vale
Project configuration
docStatic projects include a .vale.ini at the repository root. The key settings are:
| Setting | Value | Purpose |
|---|---|---|
StylesPath | .vale/styles | Directory for downloaded and custom style packages |
MinAlertLevel | suggestion | Show all findings (suggestion, warning, error) |
[formats] | mdx = md | Treat .mdx files as Markdown |
Sync styles
After cloning the repo, run vale sync once to download the style packages listed in .vale.ini:
vale sync
This populates .vale/styles/ with the configured packages. Add .vale/styles/ to .gitignore so downloaded packages are not committed.
Lint your docs
Run Vale against the docs/ directory:
vale docs/
Or lint a single file:
vale docs/guides/my-page.mdx
Vale outputs findings grouped by file, with the line number, alert level, and the rule that triggered.
Adding style packages
Vale has a library of community style packages (Google, Microsoft, write-good, and more). To add one, reference it in .vale.ini under BasedOnStyles:
[*.{md,mdx}]
BasedOnStyles = Vale, Google
Then run vale sync again to download it.
You can add project-specific rules as YAML files inside .vale/styles/. See the Vale documentation for the rule format.
Editor integration
Vale has extensions for VS Code (Vale VSCode) and other editors that surface findings inline as you write.