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

topic, source_keys

topic	source_keys
configuration	context7-websites-vale-sh

.vale.ini Structure

Configuration is INI-formatted with three sections, in order:

# Core settings appear at the top
# (the "global" section).

[formats]
# Format associations appear under
# the optional "formats" section.

[*]
# Format-specific settings appear
# under a user-provided "glob"
# pattern.

Core (global) settings apply application-wide; glob sections ([*], [*.md], etc.) scope settings to files matching that pattern.

Core Settings

Key	Type	Purpose
StylesPath	string	Path to all Vale-related resources (styles, dictionaries, vocab).
Packages	string[]	Packages to download and install via vale sync.
Vocab	string[]	Vocabularies to load.
MinAlertLevel	enum	Minimum severity to report: suggestion, warning, or error.
IgnoredScopes	enum	Inline-level HTML tags to ignore.
SkippedScopes	enum	Block-level HTML tags to ignore entirely.

Example:

StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale

Format Associations

Map an unrecognized extension onto a supported one so Vale lints it with the right parser. This is an extension-level substitution only — it does not add new file-type support:

[formats]
mdx = md

Vocabularies

Reference a named vocabulary (a folder of accept/reject word lists under StylesPath) via Vocab, then apply styles per glob:

StylesPath = styles

Vocab = Blog

[*]
BasedOnStyles = Vale, MyStyle

Packages

Third-party style packages are declared via Packages and then activated per glob with BasedOnStyles:

Packages = Google, write-good

[*.md]
BasedOnStyles = Vale, Google, write-good

Local Overrides

A project can layer a local .vale.ini that overrides StylesPath, adds packages, and changes BasedOnStyles for a subset of files — local settings merge with or override the global ones:

StylesPath = localpath

Packages = write-good

[*.md]
BasedOnStyles = write-good

Rule Header Fields

Individual rule YAML files (under a style's directory) support these header fields:

Field	Required	Default	Purpose
extends	yes	—	Check this rule extends (e.g. existence).
message	yes	—	Message shown when triggered; supports %s formatting per check type.
level	no	suggestion	Severity: suggestion, warning, or error.
scope	no	text	Scope the rule applies to (e.g. heading).
link	no	—	URL with more info about the rule.
limit	no	—	Max number of triggers per file.
vocab	no	true	Set false to disable active vocabularies for this rule.