holocron/plugins/lint/docs/research/docs/vale/overview.md

topic, source_keys

topic	source_keys
overview	context7-websites-vale-sh

What Vale Is

Vale is a cross-platform command-line tool that brings code-like linting to prose. Rather than checking general grammar, it enforces project-specific writing style rules — consistency of terminology, phrasing, and formatting — the same way a linter enforces a code style guide.

Styles, Rules, and Checks

Vale's configuration model has three layers:

• Styles — a named collection of rules (e.g. the built-in Vale style, or third-party styles like Google or write-good). A project can apply multiple styles at once via BasedOnStyles.
• Rules — individual YAML files that define one specific check (e.g. flag a term, enforce a heading capitalization pattern). Each rule extends a check and sets a message, level, and other header fields.
• Checks — the underlying functions a rule extends to perform analysis: existence, substitution, occurrence, repetition, consistency, conditional, capitalization, metric, spelling, sequence, script.

Built-in Style

Vale ships with a default Vale style containing four rules:

• Vale.Spelling — spell-checks against Hunspell-compatible dictionaries in <StylesPath>/config/dictionaries.
• Vale.Terms — enforces the project's accepted vocabulary terms.
• Vale.Avoid — enforces the project's rejected vocabulary terms.
• Vale.Repetition — flags repeated words (e.g. "the the").

Styles Directory Layout

Styles live under StylesPath in a nested folder structure, one subdirectory per style, each holding YAML rule files:

styles/
├── base/
│   ├── ComplexWords.yml
│   ├── SentenceLength.yml
├── blog/
│   ├── TechTerms.yml
└── docs/
    ├── Branding.yml

This lets a project mix a shared base style with format- or section-specific styles, all activated per-glob in .vale.ini.