Vale Linter: The Complete Guide for Docs Teams in 2026

The Vale linter does for prose what ESLint does for JavaScript. You define rules, point it at your Markdown, and it flags every passive voice, every banned word, every missing Oxford comma before a reviewer ever sees the pull request. Datadog uses it to keep 14 writers consistent across 35 product areas. GitLab, Microsoft, Mozilla, and the Linux Foundation use it too.

If you write documentation and you don't have an automated style check, you're paying a hidden tax. Reviewers spend cycles on the same nits, contributors guess at house style, and your docs drift section by section. This guide walks through what Vale is, how to install it, how to configure it, how to write custom rules, and how to wire it into CI. By the end you'll have a working setup. The patterns here also pair well with a broader documentation style guide and a clean documentation workflow.

What is the Vale linter?

Vale is an open-source command-line tool that lints prose against a configurable set of style rules. It reads Markdown, AsciiDoc, reStructuredText, HTML, plain text, and a handful of other formats, then flags content that violates the rules you've defined. It runs on macOS, Linux, and Windows, written in Go, distributed as a single binary.

The Vale linter is built around three concepts. Rules are YAML files that match patterns in your prose (banned words, sentence length, capitalization). Styles are folders of related rules (the Google developer style, the Microsoft style, your own house style). Configuration is a single .vale.ini file at the root of your repo that tells Vale which styles to apply and to which file types.

That's the whole mental model. Everything else, the GitHub Action, the VS Code extension, the vocabularies, custom checks, all of it sits on top of these three primitives.

Why prose linting matters

Documentation is code. The same arguments for linting code apply to linting prose: catch consistency errors automatically, free human reviewers to focus on substance, lower the barrier to contribution. The docs-as-code movement made this concrete, and Vale is the linting layer.

Datadog's documentation team is the canonical example. Their team grew from 7 to 14 writers while their developer-to-writer ratio stayed at 200 to 1. They merge over 20,000 documentation pull requests a year. They couldn't manually enforce style on that volume. Vale catches the predictable mistakes (wordy phrasing, banned jargon, sentence length, missing Oxford commas) before a writer ever looks at the PR.

For smaller teams the math is different but the principle holds. If you're a solo founder writing your own docs, Vale catches the bad habits you don't notice. If you're a 3-person team, it prevents the slow drift between authors. Style consistency compounds.

How to install Vale

Vale ships as a single binary. There are five common install paths.

Homebrew (macOS):

brew install vale

Chocolatey or Scoop (Windows):

choco install vale
# or
scoop install vale

Linux package managers:

# Arch
pacman -S vale

# Debian/Ubuntu (via snap)
snap install vale

Docker (any platform, useful for CI):

docker run --rm -v $(pwd):/docs jdkato/vale vale README.md

Direct download: grab the latest release from the Vale GitHub releases page and add the binary to your PATH.

Verify the install:

vale --version

You should see something like vale version v3.x.x. If you're integrating Vale into a Node-based docs workflow, the vale-cli npm package wraps the same binary so it travels with your project. Either way, the underlying engine is identical.

How to configure Vale

Vale needs two things to actually run: a configuration file and at least one style.

Create a .vale.ini at the root of your repository:

StylesPath = .vale/styles
MinAlertLevel = suggestion

Packages = Microsoft, write-good

[*.{md,mdx}]
BasedOnStyles = Vale, Microsoft, write-good

Five things to know about this file:

1. StylesPath is the directory where Vale will look for and install styles. Keep it relative and commit the path so the whole team uses the same one.
2. MinAlertLevel filters how strict Vale is. Levels are suggestion, warning, error. Start at suggestion to see everything, ratchet up later.
3. Packages tells Vale to download these styles from the Vale package registry when you run vale sync.
4. [*.{md,mdx}] is a glob. The settings inside apply only to those file types. You can scope different rules to different extensions.
5. BasedOnStyles is the actual switch that turns rules on. Listing Microsoft here activates every rule in the Microsoft style. Vale is the built-in style that ships with the binary.

After saving the config, run:

vale sync

This downloads the listed packages into your StylesPath. Now run Vale against a file:

vale README.md

You'll see every line that violates a rule, the message, and the severity. That's the loop.

Vale styles: what to use

You almost never write a complete style from scratch. You start from a published style guide, then layer your own rules on top. The Vale package registry lists every public package. The ones worth knowing about:

A reasonable starting stack for a SaaS product docs team is Microsoft + write-good + alex. The Microsoft style covers consistent capitalization, sentence structure, and product naming. write-good catches filler. alex catches phrasing nobody on a public docs site wants.

If you're using Vale to enforce a corporate style guide that already exists, write a custom style instead of bending an off-the-shelf one. Custom rules are easy.

How to write custom Vale rules

A Vale rule is a YAML file inside your StylesPath. Each rule extends a check type. The common ones:

• existence: flag text matching a regex
• substitution: flag a banned phrase and suggest a replacement
• occurrence: flag when a pattern appears too often
• repetition: flag repeated words
• consistency: flag inconsistent spellings (e.g. mixing email and e-mail)
• conditional: flag pattern A unless pattern B is also present

Here's a substitution rule that bans Latin abbreviations:

# .vale/styles/MyStyle/Abbreviations.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
nonword: true
swap:
  '\b(?:e\.g\.|eg\.)[\s,]': "for example"
  '\b(?:i\.e\.|ie\.)[\s,]': "that is"
  '\betc\.': "and so on"

Here's an existence rule that flags passive voice in marketing copy:

# .vale/styles/MyStyle/PassiveVoice.yml
extends: existence
message: "Possible passive voice: '%s'."
level: warning
ignorecase: true
tokens:
  - '\b(am|is|are|was|were|be|been|being)\s+\w+ed\b'

To activate your custom style, create the folder structure .vale/styles/MyStyle/, drop the YAML rules in, then add MyStyle to BasedOnStyles in your .vale.ini:

[*.{md,mdx}]
BasedOnStyles = Microsoft, MyStyle

Run vale README.md again and your custom rules fire alongside the imported ones.

For product-specific vocabulary (the names of your features, API endpoints, brand spellings), use a vocabulary file instead of a rule. Vocabulary files are plain text lists at .vale/styles/config/vocabularies/MyProduct/accept.txt (terms to accept as correctly spelled) and reject.txt (terms to flag as incorrect). They prevent Vale from yelling at you about your own product names.

How to integrate Vale into CI

Once Vale runs cleanly on your laptop, push it into CI so every pull request gets the same checks.

The official path is the Vale Action for GitHub. Drop this into .github/workflows/vale.yml:

name: Vale

on:
  pull_request:
    paths:
      - "**.md"
      - "**.mdx"
      - ".vale.ini"
      - ".vale/**"

jobs:
  prose:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: errata-ai/vale-action@reviewdog
        with:
          version: 3.9.1
          files: docs
          fail_on_error: true
          reporter: github-pr-review

That config does four useful things:

1. Only runs on PRs that touch documentation files (so JS-only PRs don't get blocked)
2. Pins a specific Vale version so the CI behavior doesn't drift
3. Runs only inside the docs folder
4. Posts inline comments on the PR via reviewdog, the same way ESLint or Prettier would

For GitLab CI, the equivalent is a job that installs the Vale binary and runs vale --output=line docs/. For Bitbucket Pipelines, use the Docker image jdkato/vale. The pattern is identical: install, run, fail on errors above your threshold.

Two practical notes. First, set MinAlertLevel = warning (not error) in CI when you're rolling out. Errors block the build; warnings let the team see the output and adapt before the gate slams shut. Move to error once the noise dies down. Second, scope Vale to the actual prose. Running it on auto-generated API reference markdown is mostly a waste. Add an exclude list with --glob or path-scoped rules.

Vale in your editor

CI is the gate. Your editor is the feedback loop. Get Vale running locally too.

VS Code: install the Vale extension. It picks up your .vale.ini automatically, highlights issues inline, and lists everything in the Problems tab. Pair it with the Markdown All in One extension and you have a working prose IDE.

JetBrains IDEs (WebStorm, PyCharm, IntelliJ): the Vale plugin gives you the same inline highlighting in any JetBrains tool.

Neovim: use vale-ls (the official Vale language server) wired through nvim-lspconfig.

Sublime Text: install the SubVale package via Package Control.

The shape of the loop matters more than the editor. Issues highlighted as you type beat issues caught at PR time, which beat issues caught in review. Push the feedback as left as it will go.

Vale vs alternatives

Vale isn't the only prose checker. Here's how it stacks up against the ones you'll see most often.

The clearest functional split is between rule-based tools you can configure (Vale) and heuristic tools you take as-is (alex, write-good, proselint). For a team that wants its house style enforced exactly, Vale is the only serious option. The heuristic tools are useful as Vale packages that supplement your custom rules, not as replacements.

If you compare across the broader technical writing tools ecosystem (Markdown editors, doc generators, hosting platforms), Vale fills the linting slot. Nothing else does it nearly as well.

When Vale isn't the answer

Vale is a linter. It checks prose that already exists. If you haven't written the prose yet, Vale doesn't help.

That's a real problem for most SaaS teams. The hardest part of documentation isn't keeping style consistent, it's getting the first draft written at all. Vale enforces style on the prose you've already written. If you haven't written any docs yet, AI documentation platforms like Docsio generate the first draft from your website (branding, structure, content, all of it) in a few minutes, then Vale keeps the writing on-style as you iterate. Different stages of the same workflow.

The other case where Vale isn't worth setting up: tiny content surface. If your docs are a 500-word README, the overhead of installing Vale, picking styles, configuring CI, and running it locally outweighs the consistency win. Re-read it twice and ship. Vale starts paying for itself somewhere around 20 pages, when nobody can hold the whole style in their head anymore. For everything above that threshold, plug it into your documentation review process and let it do the predictable work.

Practical setup checklist

If you're starting from zero, here's the shortest path to a working Vale setup:

1. Install Vale via Homebrew, Chocolatey, or Docker
2. Create .vale.ini at the repo root with Microsoft + write-good as the starting stack
3. Run vale sync to download styles
4. Run vale docs/ locally and skim the output to set a sensible MinAlertLevel
5. Add a vocabulary file at .vale/styles/config/vocabularies/{ProductName}/accept.txt for your product names
6. Install the Vale VS Code extension and confirm inline highlighting works
7. Add the errata-ai/vale-action GitHub Action with MinAlertLevel = warning to start
8. Watch the first 10 PRs, tune accept.txt and rule severity based on noise
9. Switch the CI threshold to error once the noise is gone
10. Write your first custom rule (start with a substitution rule for banned phrases)

You don't need everything on day one. The first three steps get you 60% of the value in 20 minutes.

Frequently asked questions

Is Vale free?

Vale is fully open source under the MIT license. The CLI, the styles, the GitHub Action, the editor integrations, all free. The maintainers run Vale Studio as a hosted UI on top of the open-source engine, but the linter itself is free for any team, any size, commercial or otherwise.

Does Vale check grammar?

Vale checks style, not grammar. It catches passive voice, banned words, sentence length, and pattern-based issues, but it won't catch subject-verb disagreement or misplaced modifiers. For grammar, pair Vale with LanguageTool or Grammarly in your editor. The two tools cover different layers and don't conflict.

Can Vale fix issues automatically?

Vale flags issues, it does not auto-fix them by default. Substitution rules suggest a replacement and you can apply fixes in supported editors, but Vale is not a formatter like Prettier. The reasoning is that prose fixes often need human judgment to keep meaning intact. For mechanical Markdown issues (spacing, headings, list markers), use markdownlint alongside Vale.

How do I suppress a Vale warning?

Use a Vale comment to disable rules inline: <!-- vale Microsoft.Foo = NO --> turns off Microsoft.Foo for the rest of the file, and <!-- vale Microsoft.Foo = YES --> turns it back on. To exclude entire files, set a [!path] block in your .vale.ini. Don't suppress to silence noise, fix the underlying rule.

What's the difference between Vale and Vale Studio?

Vale is the open-source CLI you install and run yourself. Vale Studio is a hosted product from the same maintainer that adds a web UI, team management, and analytics on top of the CLI. Studio is optional. Most teams run the CLI plus a GitHub Action and never need Studio.

Final word

Vale is the closest thing to a standard prose linter in the docs-as-code world. It's free, fast, configurable, and battle-tested at companies that ship documentation at serious volume. If your team writes more than 20 pages of docs, install it this week.

Style enforcement is the second half of the documentation problem. The first half is getting the docs written. Docsio generates a complete branded documentation site from your product URL, then hands it off to you in a Docusaurus repo you can wire straight into a Vale CI pipeline. Try the free plan, ship a site, drop in .vale.ini. The whole loop, from blank page to linted prose, takes under an hour.