Skip to main content
Vale uses an INI-style configuration file named .vale.ini to define how it processes your documentation. This file controls everything from which styles to apply to how different file formats are handled.

​
Configuration File Location

Vale searches for configuration files in the following order:
  1. Command-line flag: Specified via --config
  2. Environment variable: Set via VALE_CONFIG_PATH
  3. Local search: Walk up directory tree from current directory
  4. Home directory: Check for .vale.ini in your home directory
  5. Global config: User config directory (loaded in addition to other sources)
The search process stops at the first .vale.ini file found (except for the global config, which is always loaded if present).
Vale supports multiple file names for backwards compatibility: .vale, _vale, vale.ini, .vale.ini, and _vale.ini. However, .vale.ini is the recommended and documented standard.

​
File Structure

A .vale.ini file consists of three main sections:

​
Core Section

The unnamed section at the top defines global configuration: 
StylesPath = .github/styles
MinAlertLevel = suggestion
Vocab = ProjectName
Packages = Google, Microsoft

​
Global Section

The [*] section defines settings that apply to all files: 
[*]
BasedOnStyles = Vale, Google
Vale.Spelling = YES

​
Syntax-Specific Sections

Sections with glob patterns define settings for specific file types: 
[*.md]
BasedOnStyles = Vale, Google

[*.{rst,adoc}]
BasedOnStyles = Vale, Joblint

[docs/*.md]
Vale.Spelling = NO

​
Core Configuration Options

These options must be defined in the core section (before any [section] headers).
​
StylesPath
string
required
The path to your styles directory. Can be absolute or relative to the config file.
StylesPath = .github/styles
​
MinAlertLevel
string
default:"suggestion"
Minimum alert level to display. Must be one of: suggestion, warning, or error.
MinAlertLevel = warning
​
Vocab
string | array
Project vocabulary to load from config/vocabularies/[name]/. Supports multiple vocabularies separated by commas.
Vocab = ProjectName, Acronyms
See the Vocabularies documentation for more details.
​
Packages
array
External configuration packages to install via vale sync. Comma-separated list of package names or URLs.
Packages = Google, Microsoft, https://example.com/style.zip
See the Packages documentation for more details.
​
IgnoredScopes
array
HTML/markup scopes to ignore completely. Vale will not process text within these scopes.
IgnoredScopes = code, tt, script
​
SkippedScopes
array
HTML/markup blocks to skip. Similar to IgnoredScopes but applies to block-level elements.
SkippedScopes = script, style, pre, figure, blockquote
​
IgnoredClasses
array
HTML classes to ignore. Elements with these classes will not be processed.
IgnoredClasses = no-prose, skip-vale
​
WordTemplate
string
Template for converting YAML lists to regular expressions. Used by style rules that reference vocabulary files.
WordTemplate = \\b(?:%s)\\b
​
NLPEndpoint
string
External API endpoint for NLP-related processing. Used by advanced rules that require natural language processing.
NLPEndpoint = http://localhost:8080/nlp

​
Global Options

These options can be defined in the [*] section or in syntax-specific sections.
​
BasedOnStyles
array
Styles to load from your StylesPath. Comma-separated list of style names.
[*]
BasedOnStyles = Vale, Google
​
BlockIgnores
array
Regular expression patterns for blocks of text to ignore.
[*.md]
BlockIgnores = (?s)```.*?```
​
TokenIgnores
array
Regular expression patterns for inline tokens to ignore.
[*.md]
TokenIgnores = ({%.+?%}), ({{.+?}})

​
Syntax-Specific Options

These options can only be defined in syntax-specific sections (e.g., [*.md]).
​
Transform
string
Path to an XSLT stylesheet for transforming XML files before processing.
[*.xml]
Transform = .vale/transform.xsl
​
Lang
string
Language identifier for syntax highlighting and language-specific processing.
[*.mdx]
Lang = javascript
​
CommentDelimiters
array
Start and end delimiters for comment blocks. Must be exactly two values.
[*.c]
CommentDelimiters = {/*, */}
​
View
string
Custom view definition from config/views/[name].yml for extracting specific content from structured files.
[*.json]
View = APISchema

​
Rule Configuration

Individual rules can be enabled or disabled at both global and syntax-specific levels: 
[*]
Vale.Spelling = YES
Google.Headings = error

[*.md]
Vale.Spelling = NO
Google.Passive = warning
Microsoft.Contractions = suggestion
Rule levels can be YES, NO, suggestion, warning, or error. The YES value inherits the level from the rule definition, while specific levels override it.

​
Configuration Hierarchy

When multiple configuration sources are present, they are merged in this order:
  1. Project config (from local search or flags)
  2. Default styles (if VALE_STYLES_PATH is set)
  3. Global config (from user config directory)
  4. Command-line flags (override all other settings)
Later sources override earlier ones for conflicting options, while arrays are merged.

​
Example Configuration

Here’s a complete example showing common configuration patterns: 
# Core settings
StylesPath = .github/styles
MinAlertLevel = suggestion

Vocab = MyProject
Packages = Microsoft, Google

IgnoredScopes = code, tt
SkippedScopes = script, style, pre

# Formats mapping
[formats]
ts = js
mdx = md

# Global rules
[*]
BasedOnStyles = Vale

# Markdown files
[*.md]
BasedOnStyles = Vale, Microsoft
TokenIgnores = ({%.+?%})

# Documentation directory
[docs/*.md]
BasedOnStyles = Vale, Microsoft, Google
Microsoft.Contractions = NO

# Code comments
[*.{js,ts}]
BasedOnStyles = Vale
Vale.Spelling = YES

​
Configuration Validation

Validate your configuration with: 
vale ls-config
This prints your merged configuration as JSON, showing exactly how Vale interprets your settings.
Use vale ls-dirs to see where Vale looks for configuration files and related assets on your system.

Build docs developers (and LLMs) love

Get started for freeTalk to us