cloudparts

Vale

A command-line linter for prose: it parses Markdown, AsciiDoc, HTML and code comments, then checks the text against style rules written as YAML files.

What it is
Linters, formatters and type checkers (prose linters)
Type
Open source
Made by
Joseph Kato and contributors (community project)
License
MIT
Facts checked
23 October 2026

What it is

Vale turns a writing style guide into checks that run in the editor and in CI. It ships almost no opinions of its own. A style is a folder of YAML rules, each built on one of 12 checks: existence flags listed words or patterns, substitution suggests a replacement, capitalization checks headings, readability scores a grade level with formulas such as Flesch-Kincaid and SMOG, spelling uses Hunspell dictionaries, and script runs custom logic. A .vale.ini file says which styles apply to which files, and vale sync downloads published packages such as Microsoft’s and Google’s style guides, proselint, write-good and alex.

What sets it apart is that it reads documents, not raw text. Markdown, AsciiDoc, reStructuredText, HTML and other formats go through a real parser, so a rule can target headings, lists or table cells, and code spans, URLs and fenced blocks are skipped. It lifts comments and docstrings out of source code with tree-sitter grammars, and “views” point it at the prose inside an OpenAPI file, a notebook or a commit message. It is a single Go binary that runs offline. Recent releases added rule inheritance, a standard library of rules (Std) and Voices, a package that turns the instructions people give LLMs about tone, such as “don’t hedge” or “no puffery”, into rules that check every draft.

Why teams pick it

  • Markup-aware: rules can target parts of a document, and code, URLs and front matter don’t raise false alarms
  • A house style becomes a folder of YAML files that anyone can read, review and extend, with no programming needed for most rules
  • One offline binary for macOS, Windows and Linux, so CI and editors need no Node.js or Python
  • A large ecosystem: published styles, a language server, a GitHub Action, and built-in use in docs platforms such as Mintlify

Watch out for

  • Rules match words and patterns; Vale doesn’t understand meaning, so it can’t tell whether a sentence is correct or clear
  • Big word-list styles report many suggestions on existing docs until you tune levels, exceptions and vocabularies
  • Every project needs a .vale.ini and a vale sync step before the first run
  • Developed by one maintainer, funded by sponsors and grants

Alternatives

What all prose linters have in common →Compare side by side →

How it fits with other technologies

A house rule (styles/House/Hedging.yml) and the config that enables it · yaml

# .vale.ini
#   StylesPath = styles
#   MinAlertLevel = suggestion
#   Packages = Microsoft
#   [*.md]
#   BasedOnStyles = Vale, Microsoft, House

extends: existence
message: Consider removing '%s'
level: warning
ignorecase: true
tokens:
  - appears to be
  - arguably

# $ vale docs/
#  docs/install.md
#  3:7  suggestion  Consider using 'use' instead of 'utilize'.  Microsoft.Wordiness

See it in a real stack

No architecture uses Vale yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2017–2026

Earlier prose checkers such as proselint (Python) and write-good (Node.js) each needed their own language runtime and had little support for markup. Joseph Kato released Vale in February 2017 as a linter for prose “no matter if it’s plain text, markup or source-code comments”, written in Go and built around rules anyone could add. The 1.0 release in August 2018 bundled proselint, write-good and Joblint as styles, listing better markup support and a single binary as the reasons to use them through Vale.

Vale 2.0 (February 2020) took those bundled styles out into separate packages, so Vale itself carried only a minimal built-in style, and added XML and DITA support. Vale 3.0 (January 2024) added a default configuration and a shared config folder for dictionaries and vocabularies. The project, now under the vale-cli GitHub organisation, received a $10,000 FLOSS/fund grant in 2025, and in 2026 added rule inheritance, the Std library and Voices, aimed at checking text written by coding agents as well as people.

Why it’s built this way

Parse markup instead of reading plain text
Docs are written in Markdown, AsciiDoc or HTML full of code and links; parsing lets rules ignore code and target headings or other parts of a document.
Rules as YAML files, not code
Editors and technical writers maintain style guides, so a rule had to be something they could write and review without programming.
No opinions in the core
Every organisation has its own style, so Vale ships the engine and leaves the rules to packages, which 2.0 split out of the binary.
One standalone Go binary
Avoid the Node.js or Python install that write-good and proselint needed, so the same tool runs in any editor and CI.

Timeline

  1. 2017

    February: first release (0.1.0)

  2. 2018

    August: 1.0, bundling proselint, write-good and Joblint styles

  3. 2020

    February: 2.0 moves styles into separate packages and adds XML

  4. 2024

    January: 3.0 adds a default config and a shared config folder

  5. 2025

    $10,000 grant from FLOSS/fund

  6. 2026

    September: 3.20 adds rule inheritance, with the Std and Voices packages

Sources12 · facts checked 23 October 2026

Improve this page on GitHub