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.iniand avale syncstep 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 →
ReadableCommercialA hosted readability service, with an HTTP API, that scores text or a web page with 15 readability formulas, CEFR and IELTS levels, an A–E rating, tone and sentiment, and highlights long sentences, passive voice, clichés and hedge words.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.WordinessSee 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.
Timeline
- 2017
February: first release (0.1.0)
- 2018
August: 1.0, bundling proselint, write-good and Joblint styles
- 2020
February: 2.0 moves styles into separate packages and adds XML
- 2024
January: 3.0 adds a default config and a shared config folder
- 2025
$10,000 grant from FLOSS/fund
- 2026
September: 3.20 adds rule inheritance, with the Std and Voices packages
Sources12 · facts checked 23 October 2026
- Vale README
- Vale docs
- Vale docs: Styles
- Vale docs: Checks
- Vale docs: existence check
- Vale docs: readability check
- Vale blog: Introducing Voices (Sep 2026)
- Vale package: alex
- Vale blog (posts on commit messages, GOV.UK, Voices, Std)
- Vale GitHub Action
- Vale agent tools (Claude Code plugin and hook)
- Vale release v3.25.1 (Oct 2026)