Vale — Syntax-Aware Prose Linter for Technical Writing

Introduction

Vale is a fast, extensible prose linter that brings the rigor of code linting to technical writing. Created by Joseph Kato, it allows documentation teams to codify their style guide into machine-checkable rules and enforce them in CI pipelines. Vale understands markup formats natively, so it only lints prose content — not code blocks, front matter, or markup syntax.

What Vale Does

• Lints Markdown, AsciiDoc, reStructuredText, HTML, DITA, and XML documents
• Enforces style rules covering word usage, sentence structure, jargon, and tone
• Ships with ready-to-use style packages from Google, Microsoft, write-good, and Joblint
• Integrates with CI/CD pipelines, VS Code, Vim, Emacs, and JetBrains editors
• Supports custom YAML-based rules with regex patterns, scoping, and conditional logic

Architecture Overview

Vale is written in Go and distributed as a single static binary. At runtime, it parses each input file into an abstract syntax tree using format-specific parsers (goldmark for Markdown, etc.), then walks the AST applying scoped rules. Rules are defined as YAML files organized into style packages. Each rule specifies a scope (sentence, paragraph, heading, etc.), a matching pattern (regex, substitution list, or occurrence count), and a severity level. Vale resolves the configuration hierarchy from .vale.ini files, allowing per-directory overrides.

Self-Hosting & Configuration

• Install via Homebrew, Chocolatey, Docker, or download prebuilt binaries
• Create .vale.ini at your project root to define styles path and file associations
• Run vale sync to download style packages defined in your config
• Write custom rules as YAML files in your styles directory
• Add Vale to CI with vale --output=JSON docs/ for machine-readable results

Key Features

• Format-aware parsing that skips code blocks, front matter, and inline code
• 30+ pre-built style packages including Google Developer, Microsoft Writing, and AP Style
• Custom rule authoring with YAML using regex, substitution maps, and token sequences
• Vocabulary files for managing accepted and rejected terminology per project
• Editor integrations for real-time feedback during writing

Comparison with Similar Tools

• markdownlint — checks Markdown formatting rules (headings, lists) rather than prose style
• textlint — JavaScript-based prose linter with plugin architecture, slower and requires Node.js
• Grammarly — cloud-based grammar checker without custom rule support or CI integration
• LanguageTool — grammar and spell checker with different focus (correctness vs. style consistency)
• alex — catches insensitive writing but covers a narrower scope than Vale

FAQ

Q: Can I use Vale without an existing style guide? A: Yes. Start with community packages like write-good or Google Developer Documentation Style Guide. You can customize rules incrementally.

Q: Does Vale check grammar and spelling? A: Vale focuses on style enforcement, not grammar. It can catch specific phrasing patterns you define but is not a general grammar checker. Pair it with a spell checker for full coverage.

Q: How do I create custom rules? A: Write YAML files in your styles directory. Each rule specifies a scope, pattern type (existence, substitution, occurrence, conditional), and severity. See the Vale documentation for examples.

Q: Can Vale run in CI/CD? A: Yes. Vale runs as a single binary with a non-zero exit code on errors, making it straightforward to add to GitHub Actions, GitLab CI, or any pipeline.

Sources

• https://github.com/errata-ai/vale
• https://vale.sh/docs/