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

brew install vale

Linux

# Debian / Ubuntu
sudo apt install vale

Windows

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.

Custom rules

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.