If you’ve ever worked on a large documentation project, you know how quickly things can get messy. Different contributors bring different writing styles, terminology gets inconsistent, and small grammar mistakes sneak through. That’s where Vale comes in — a linter for prose that helps keep your docs clean, consistent, and professional.

What is Vale?

Vale is an open-source command-line tool for linting and style-checking text. Think of it like ESLint or Prettier, but for documentation and prose instead of code. It helps you:

• Enforce a consistent style across docs.
• Catch grammar, spelling, and clarity issues early.
• Standardize terminology (e.g., always use “sign in” instead of “login”).
• Automate reviews so humans can focus on content, not nitpicks.

Vale works with Markdown, reStructuredText, AsciiDoc, and more — making it a great fit for docs-as-code workflows.

Why Use Vale?

• Consistency matters: Readers trust documentation that feels cohesive.
• Saves reviewer time: Automates style nitpicks so reviewers can focus on accuracy.
• Integrates with CI/CD: Catch doc issues before merging.
• Customisable: Define your own style rules or adopt existing ones (like Google or Microsoft style guides).

Installing Vale

Vale is distributed as a single binary — no big dependencies.

On macOS (via Homebrew):

brew install vale

On Linux (via binary release):

curl -s https://api.github.com/repos/errata-ai/vale/releases/latest \
| grep "browser_download_url.*Linux_64-bit.tar.gz" \
| cut -d '"' -f 4 \
| wget -qi - && tar -xzf Vale_*_Linux_64-bit.tar.gz

On Windows: download from the Vale releases page.

Setting Up Vale

In the root of your docs project, create a .vale.ini file:

StylesPath = styles
MinAlertLevel = suggestion

Packages = Google, proselint, write-good

[*.md]
BasedOnStyles = Vale, Google, proselint, write-good

This tells Vale to:

• Look for styles in the styles/ directory.
• Use Microsoft’s style guide.
• Apply it to all .md files.

Running Vale

Once configured, lint your docs with:

vale path/to/docs/

Example output:

docs/getting-started.md
 25:5  error  'login' should be written as 'sign in'  Google.Terms
 44:10 warning  Avoid using 'simply'                  Google.Avoid

Here you can see Vale catching terminology and tone issues automatically.

Customizing Rules

Vale is powerful because you can define your own style rules. For example, let’s enforce “e-mail” vs “email.”

Create a file at styles/Custom/Terms.yml:

extends: existence
message: "Use 'email' instead of 'e-mail'."
level: error
ignorecase: true
tokens:
  - e-mail

Now Vale will flag “e-mail” anywhere in your docs.

Using Vale in CI/CD

To ensure consistency across teams, add Vale to your build pipeline. For example, in GitHub Actions:

name: Lint Docs

on: [pull_request]

jobs:
  vale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Vale
        run: |
          curl -fsSL https://install.goreleaser.com/github.com/errata-ai/vale.sh | sh
          sudo mv ./bin/vale /usr/local/bin/
      - name: Run Vale
        run: vale .

This way, PRs can’t be merged until documentation passes linting.

Starter Vale Style Guide

This starter style guide enforces clear, consistent, and professional writing. It includes rules for terminology, tone, and formatting that you can extend as your docs mature.

👉 Folder structure example:

docs/
styles/
  Starter/
    Terms.yml
    Tone.yml
    Spacing.yml
.vale.ini

.vale.ini

StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Starter

This tells Vale to look in the styles/ folder and apply the Starter style to all Markdown files.

Terms.yml – Consistent Terminology

extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
  login: sign in
  log-in: sign in
  e-mail: email
  Github: GitHub
  Javascript: JavaScript

✅ Enforces consistent word choices and fixes common brand/style mistakes.

Tone.yml – Avoid Filler Words

extends: existence
message: "Avoid using '%s'."
level: warning
ignorecase: true
tokens:
  - simply
  - obviously
  - clearly
  - basically
  - just

✅ Flags words that can sound condescending or unnecessary in documentation.

Spacing.yml – Clean Formatting

extends: existence
message: "Use a single space between sentences."
level: error
nonword: true
tokens:
  - '\s{2,}'

✅ Ensures no double spaces sneak into your text.

How to Use

1. Save the above files into styles/Starter/.
2. Update .vale.ini to include Starter.
3. Run vale docs/ and watch it flag issues.

Example in Action

Input:

To login, just click the button. Github is simply awesome!

Output:

 1:4  error   Use 'sign in' instead of 'login'.       Starter.Terms
 1:11 warning Avoid using 'just'.                     Starter.Tone
 1:29 error   Use 'GitHub' instead of 'Github'.       Starter.Terms
 1:37 warning Avoid using 'simply'.                   Starter.Tone
 1:50 error   Use a single space between sentences.   Starter.Spacing

Conclusion

Vale takes the guesswork out of documentation quality. By automating style and consistency checks, it frees up writers and reviewers to focus on content and accuracy. Whether you’re maintaining internal runbooks, public APIs, or open-source docs, Vale helps you deliver polished, professional writing every time.

This starter style guide gives you:

• Terminology enforcement (consistent words, correct brands).
• Tone checks (avoid filler or condescending words).
• Formatting rules (like spacing).

It’s lightweight but effective — and you can extend it with custom rules as your docs grow.

If you’re serious about treating docs like code, adding Vale to your toolchain is a no-brainer.