Vale: Prose Linter

What it is

Vale is a command-line tool that lints writing the way ESLint or Pylint lint code. It understands markup, so it checks headings, lists and paragraphs while skipping code blocks and URLs. Rules are written in YAML, and you can install published style packages, including ones based on the Microsoft, Google and Red Hat style guides.

According to its site, Vale supports 12 markup formats including Markdown, AsciiDoc, reStructuredText, MDX, HTML and DITA, and can check documentation comments in 19 programming languages. It ships as a single Go binary for macOS, Windows and Linux. The site reports 14 million downloads and lists organisations such as Amazon Web Services, Microsoft, Discord, GitLab and NVIDIA among its users.

Why it matters

A style guide only helps if people follow it, and reviewers get tired of leaving the same comment about passive voice or banned words. Vale moves the mechanical checks into automation so human review can focus on accuracy and clarity. Many documentation teams run it in pull requests next to link checkers and build checks.

For a technical writing portfolio, a repository with a Vale config and a CI check shows that you understand docs as code, which employers value.

Prerequisites

Comfort with a terminal, a text editor and Git. Setting it up in CI needs a basic understanding of a pipeline tool such as GitHub Actions.

How to start

1. Install Vale and create a .vale.ini in a docs repository.
2. Add the Google or Microsoft package and run vale sync to download it.
3. Run it on your docs and read each alert. Decide which rules suit your project and turn off the rest.
4. Add a VS Code extension for inline alerts.
5. Add a CI step so every pull request is checked.

Limits

Vale checks patterns, not meaning. It cannot tell you whether a procedure works or an explanation is correct. Too many noisy rules also make people ignore it, so start small.

Free vs paid

Free and open source under the MIT licence.

Common questions

Is it only for technical writers? No. Developers use it on READMEs, and developer advocates use it on tutorials and blog posts.

Does it replace an editor? No. It removes the repetitive checks so an editor or reviewer can spend time on substance.