# Vale — Syntax-Aware Prose Linter for Technical Writing

> Vale is a command-line tool that enforces writing style guides on your prose, supporting custom rules for documentation teams to ensure consistent terminology, tone, and formatting across Markdown, AsciiDoc, and more.

## Install

Save in your project root:

# Vale — Syntax-Aware Prose Linter for Technical Writing

## Quick Use
```bash
# Install Vale
brew install vale
# or download from GitHub releases

# Initialize with a style guide
vale sync

# Create a .vale.ini config
cat << EOF > .vale.ini
StylesPath = styles
MinAlertLevel = suggestion
[*.md]
BasedOnStyles = Vale, write-good
EOF

# Lint your documentation
vale docs/
```

## 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/

---
Source: https://tokrepo.com/en/workflows/13b1fee7-3cf7-11f1-9bc6-00163e2b0d79
Author: AI Open Source