Skip to main content
Vale Hero Light

​
What is Vale?

Vale is a command-line tool that brings code-like linting to prose. Written in Go, it’s designed to be fast, cross-platform, and highly customizable. Unlike traditional grammar checkers, Vale understands markup formats and can enforce your organization’s specific style guidelines.

Lightning Fast

Built with performance in mind, Vale can lint thousands of files in seconds. Benchmarks show it’s significantly faster than alternatives like textlint and proselint.

Markup-Aware

Native support for Markdown, AsciiDoc, reStructuredText, HTML, XML, and Org. Vale intelligently excludes code snippets and understands document structure.

Extensible Rules

Create custom rules using simple YAML files. No programming required. Choose from 12 built-in rule types to enforce any style guideline.

No Dependencies

Stand-alone binary with zero dependencies. No need to install Python, Node.js, or any runtime environment.

​
Key Features

1

Syntax-Aware Linting

Vale parses markup formats at the AST level, avoiding false positives in code blocks, frontmatter, and other non-prose content. It can scope rules to specific elements like headings, links, or blockquotes.
2

Flexible Configuration

Configure Vale using .vale.ini files that can live in your project root or home directory. Set different styles for different file types, control which rules apply where, and adjust severity levels.
3

Style as Code

Vale rules are written in YAML and can be version-controlled alongside your content. Share styles across teams, contribute to community styles, or build your own from scratch.
4

CI/CD Integration

Vale returns appropriate exit codes and supports JSON output, making it perfect for continuous integration pipelines. Catch style issues before they reach production.

​
Why Vale?

Most linters for prose fall into one of two categories:
  1. Opinionated tools that enforce a fixed set of rules you can’t customize
  2. Extensible tools that require you to write JavaScript, Python, or Java to create rules
Vale takes a different approach: it’s designed from the ground up to be both extensible and accessible. With Vale, anyone can create sophisticated style rules using declarative YAML syntax. 
# Flag words that shouldn't appear in your content
extends: existence
message: "Avoid using '%s'"
level: error
tokens:
  - obviously
  - simply
  - just
  - easy

​
How Vale Works

Vale processes your content in three stages:
1

Parse

Vale reads your file and determines its format (Markdown, HTML, etc.). It then parses the content into an abstract syntax tree (AST), identifying prose elements versus code, metadata, and other non-prose content.
2

Scope

Based on your configuration and each rule’s scope, Vale determines which rules apply to which parts of the document. A rule scoped to heading only checks headings, while text checks all prose.
3

Lint

Vale runs applicable rules against each text block, checking for pattern matches, readability metrics, spelling errors, and more. It generates alerts with line numbers, severity levels, and suggested fixes.

​
Vale’s Architecture

Vale is organized into several internal packages, each handling specific functionality:
  • check: Loads and validates YAML rules, compiles regex patterns, and manages the rule execution engine
  • core: Defines core data structures like File, Alert, and Config, and handles INI configuration parsing
  • lint: Manages the linting process, including format detection, AST parsing, and rule application
  • nlp: Provides natural language processing capabilities for readability metrics and tokenization
  • spell: Implements spell checking with support for Hunspell dictionaries

​
What You Can Build

Style Guides

Enforce your organization’s style guide: AP, Chicago, Microsoft, Google, or your own custom guidelines.

Terminology Management

Maintain consistent terminology across your documentation. Define accepted terms and flag deprecated alternatives.

Readability Standards

Set readability targets using metrics like Flesch-Kincaid, Gunning Fog, or custom formulas.

Inclusive Language

Identify and suggest alternatives for language that may not be inclusive or could be insensitive.

​
Comparison with Other Tools

Vale stands out among prose linters:
FeatureValetextlintproselintwrite-good
ExtensibleYes (YAML)Yes (JavaScript)NoYes (JavaScript)
Markup SupportMarkdown, AsciiDoc, RST, HTML, XML, OrgMarkdown, AsciiDoc, RST, HTMLPlain text onlyPlain text only
Spell CheckingYesVia pluginsNoNo
PerformanceExcellentGoodGoodGood
DependenciesNoneNode.jsPythonNode.js
LicenseMITMITBSD 3-ClauseMIT
Benchmarks show Vale is significantly faster than alternatives. On a corpus of 1,500 Markdown files, Vale completes in under 2 seconds while comparable tools take 10-30 seconds.

​
Real-World Usage

Vale is used by documentation teams at:
  • GitLab: Enforcing their documentation style guide across thousands of pages
  • Spotify: Maintaining consistency in technical documentation
  • Homebrew: Ensuring formula descriptions follow conventions
  • Linode: Checking technical tutorials and guides
  • And hundreds more: From startups to enterprises

​
Next Steps

Installation

Install Vale on macOS, Linux, or Windows in minutes.

Quick Start

Get Vale running on your first project in under 5 minutes.

Core Concepts

Learn about styles, scoping, and configuration.

Writing Rules

Create your first custom Vale rule.

​
Community and Support

GitHub

Source code, issues, and discussions

Package Hub

Pre-built style packages for popular style guides

Rule Explorer

Browse and test rules interactively

Build docs developers (and LLMs) love

Get started for freeTalk to us