Static Site Generators in Production

Editorial Checks with Vale in CI

Documentation teams that work in Git get code review for free, but editorial review is still mostly human: a reviewer spots "click on" instead of "select", a product name in the wrong case, a sentence of 60 words, or a term the style guide banned last year. Those comments are repetitive, easy to miss and a poor use of an editor's time. Vale automates them. It is a prose linter that applies your style guide to every changed file and reports issues inline on the pull request.

This guide sets up Vale for a Markdown documentation repository, chooses a starting rule set, adds a project vocabulary, runs it in GitHub Actions with inline comments, and rolls it out without overwhelming writers. It is part of Content Workflows for Documentation Teams.

Prerequisites

  • Documentation in Markdown, MDX, AsciiDoc or reStructuredText in a Git repository.
  • A pull request workflow — see Docs-as-Code Review Workflow for Writers.
  • Vale installed locally for testing (brew install vale or a release binary).

How Vale Works

Vale parses each document into scopes — headings, paragraphs, lists, tables — and skips code blocks, inline code and front matter by default. Rules are YAML files grouped into styles. Each rule has a type (existence, substitution, capitalization, occurrence, readability, spelling and others), a message and a level: suggestion, warning or error.

How Vale checks a document in a pull request Changed Markdown files are parsed into scopes, with code blocks and front matter skipped. Styles and the project vocabulary are applied. Results at suggestion and warning level become review comments; error-level results fail the check. From changed file to review comment changed .md files from the PR diff parse into scopes skip code, front matter apply styles Vale, Microsoft, House suggestion, warning inline comment error check fails vocabulary: accept.txt (product names, jargon) · reject.txt (banned terms) only changed lines are reported, so legacy pages do not flood new pull requests
Warnings guide writers; only agreed error rules block the merge.

Configuring Vale

Create .vale.ini at the repository root:

StylesPath = .github/styles
MinAlertLevel = suggestion
Vocab = Docs
Packages = Microsoft

[*.{md,mdx}]
BasedOnStyles = Vale, Microsoft, House
Microsoft.Contractions = NO
Microsoft.Headings = warning
Vale.Terms = error

Packages downloads published styles with vale sync. BasedOnStyles lists the styles to apply; House is your own folder of rules under StylesPath. Individual rules can be turned off (NO) or have their level changed, which is how you adapt a published style to your guide without forking it.

Run vale sync once, then vale docs/ to see what the current content looks like. Expect thousands of results on an existing site; the rollout section below handles that.

Vocabulary and House Rules

A vocabulary is two text files under StylesPath/config/vocabularies/Docs/. accept.txt lists terms that are correct — product names, API names, jargon — one per line, with regular expressions allowed. They stop spelling false positives, and the Vale.Terms rule flags incorrect capitalisation, so "Github" becomes an error when "GitHub" is in the list. reject.txt lists terms that must never appear.

House rules capture the parts of your style guide that published packages do not. A substitution rule for preferred terms:

# .github/styles/House/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: warning
ignorecase: true
swap:
  click on: select
  e-mail: email
  log into: log in to
  whitelist: allowlist
  blacklist: blocklist

And a readability rule for sentence length:

# .github/styles/House/SentenceLength.yml
extends: occurrence
message: "Try to keep sentences under 30 words."
level: suggestion
scope: sentence
max: 30
token: \b(\w+)\b

Keep house rules small and specific. Each one should correspond to a line in the written style guide, so writers can look up the reason.

Running Vale in GitHub Actions

The official errata-ai/vale-action runs Vale on changed files and posts results through reviewdog as inline pull request comments:

name: Docs lint
on:
  pull_request:
    paths: ['docs/**', '.vale.ini', '.github/styles/**']

jobs:
  vale:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: errata-ai/vale-action@v2
        with:
          files: docs
          filter_mode: diff_context
          reporter: github-pr-review
          fail_on_error: true

filter_mode: diff_context reports only issues on or near changed lines, which is what makes Vale usable on a large existing site: writers see comments about what they touched, not about every legacy page they opened. fail_on_error: true fails the check only for error-level alerts.

Rolling It Out

Turning on a hundred rules at once produces a wall of comments and a team that disables the check within a week. A staged rollout works better:

A four-stage Vale rollout Stage one, week one: spelling and product names as warnings on changed lines only. Stage two, weeks two to four: add house terms and headings as warnings. Stage three, month two: promote product names and banned terms to errors. Stage four, ongoing: fix legacy pages in batches and add rules as the style guide changes. Introduce rules in stages 1 · week 1 spelling + vocabulary warnings only changed lines only 2 · weeks 2–4 house terms heading case still warnings 3 · month 2 product names → error banned terms → error check becomes required 4 · ongoing fix legacy in batches tune noisy rules add rules with the style guide track false positives per rule; a rule writers constantly ignore needs rewording or removal
Errors should be rules nobody disagrees with; everything else stays advisory.
  1. Start with spelling and vocabulary as warnings on changed lines. It catches real mistakes and builds the accept list quickly.
  2. Add house terms and heading rules as warnings once the vocabulary settles.
  3. Promote a few rules to errors — product name capitalisation and banned terms are good candidates — and make the check required in branch protection.
  4. Clean up legacy pages in batches, one section per pull request, so each fix is reviewable.

Let writers opt out of a rule for a specific passage with comments, which Vale supports in Markdown: <!-- vale House.Terms = NO --> before and <!-- vale House.Terms = YES --> after. Review those exceptions like any other change.

Maintaining the Rules

A Vale setup is a small codebase and needs the same care. Assign an owner — usually the documentation lead — and treat changes to .vale.ini, the vocabulary and house rules as pull requests with a short rationale. The workflow's paths filter above re-runs Vale whenever the rules change, so a new rule shows its impact on the pull request that introduces it.

Every few months, look at which rules fire most and which alerts writers most often suppress with comments. A rule with many suppressions is usually either wrong for your content or worded unclearly; rewrite the message so it explains the reason, narrow its scope, or drop it. A rule that never fires may be obsolete. Keep a changelog in the style guide so writers know when a new term was banned and why, and add each new product name to the accept list on launch day rather than after the first alert.

Editor Integration

Vale is more pleasant when writers see issues while typing rather than after pushing. The Vale extension for VS Code and the Vale language server for other editors use the same .vale.ini, so local results match CI. Add a short section to the contributing guide showing how to install it and run vale sync.

Editorial review comments before and after adopting Vale Per pull request, human style comments fell from an average of 6.4 to 1.1 after three months with Vale. Median time from pull request to merge fell from 2.8 days to 1.6 days. Docs pull requests, quarter before vs quarter after 6.4 1.1 human style comments / PR 2.8 d 1.6 d median time to merge editors' remaining comments were about structure and accuracy, not wording
Automating the mechanical comments freed reviewers for the ones that need judgement.

Measured Impact

A documentation team of five writers and around forty engineering contributors adopted Vale with the staged rollout above. Over the following quarter, human style comments per pull request fell from 6.4 to 1.1, median time to merge dropped from 2.8 to 1.6 days, and product-name misspellings in published pages went from 212 to zero after two legacy clean-up batches. The accept list reached 340 terms, most added in the first two weeks.

Pitfalls & Rollback

  • Reporting on whole files. Without diff_context, every PR inherits all legacy issues; writers will ignore the check.
  • Too many errors. Subjective rules as errors block merges and breed resentment; keep them as suggestions.
  • Unpinned packages. A package update can add rules overnight; pin versions and update deliberately.
  • MDX components. Vale may parse JSX as text; configure [*.mdx] with the MDX parser or ignore component blocks.
  • Rollback: remove the workflow or make the check non-required; the configuration can stay for local use.

Conclusion

Vale turns the mechanical half of editorial review into an automated check: spelling, terminology, capitalisation, banned words and readability, applied consistently to every pull request. Configure it with a published style plus a small house style and vocabulary, run it in CI on changed lines with inline comments, and roll it out in stages with only agreed rules as errors. Editors then spend their review time on structure and accuracy, which no linter can check.

FAQ

What is Vale?

Vale is an open-source, command-line prose linter. It reads Markdown, AsciiDoc, reStructuredText and HTML, applies style rules written in YAML, and reports issues with line numbers, so editorial standards can be checked automatically like code style.

Which Vale styles should a documentation team start with?

Start with a small set - Vale's own rules plus a published style such as the Microsoft or Google developer style packages - then add a custom vocabulary for product names. Enable only a few rules as errors at first and expand as the team gets used to it.

How do I stop Vale from flagging code and product names?

Vale skips fenced code blocks and inline code by default. For product names and jargon, add them to a vocabulary accept list, which both suppresses spelling errors and enforces the correct capitalisation.

Should Vale block merging pull requests?

Only for error-level rules the team has agreed on, such as banned terms and product name capitalisation. Keep suggestions and warnings non-blocking, reported as review comments, so writers are guided without being stopped by subjective rules.