Configuration

The .vale.ini file is where you'll control the majority of Vale's behavior, including what files to lint and how to lint them.

Options

The .vale.ini file is INI-formatted and consists of three sections: core settings, format associations, and format-specific settings:

.vale.ini
# 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 settings

Core settings appear at the top of the file and apply to the application itself rather than a specific file format.

StylesPath

Heads up!

Vale Server requires that all paths (on both macOS and Windows) use a forward slash (/) and be absolute file paths.

# Here's an example of a relative path:
#
# .vale.ini
# ci/
# ├── vale/
# │ ├── styles/
StylesPath = "ci/vale/styles"

StylesPath specifies where Vale should look for its external resources (e.g., styles and ignore files). The path value may be absolute or relative to the location of the parent .vale.ini file.

MinAlertLevel

MinAlertLevel = suggestion

MinAlertLevel specifies the minimum alert severity that Vale will report. The options are "suggestion", "warning", or "error" (defaults to "warning").

IgnoredScopes

# By default, `code` and `tt` are ignored.
IgnoredScopes = code, tt

IgnoredScopes specifies inline-level HTML tags to ignore. In other words, these tags may occur in an active scope (unlike SkippedScopes, which are skipped entirely) but their content still won't raise any alerts.

IgnoredClasses (v2.2)

IgnoredClasses specifies classes to ignore. These classes may appear on both inline- and block-level HTML elements.

IgnoredClasses = my-class, another-class

SkippedScopes

# By default, `script`, `style`, `pre`, and `figure` are ignored.
SkippedScopes = script, style, pre, figure

SkippedScopes specifies block-level HTML tags to ignore. Any content in these scopes will be ignored.

WordTemplate

WordTemplate = \b(?:%s)\b

WordTemplate specifies what Vale will consider to be an individual word.

SphinxBuildPath (v2.0)

SphinxBuildPath = _build

SphinxBuildPath is the path to your _build folder (relative to the configuration file).

SphinxAutoBuild (v2.0)

SphinxAutoBuild = make html

SphinxAutoBuild is the command that builds your site (make html is the default for Sphinx).

If this is defined, Vale will re-build your site prior to linting any content—making it possible to use Sphinx and Vale in lint-on-the-fly environments (e.g., text editors) at the cost of performance.

Format associations

Format associations allow you to associate an "unknown" file extension with a supported file format:

[formats]
mdx = md

In the example above, we're telling Vale to treat MDX files as Markdown files.

Format-specific settings

Format-specific sections apply their settings only to files that match their associated glob pattern.

For example, [*] matches all files while [*.{md,txt}] only matches files that end with either .md or .txt.

You can have as many format-specific sections as you'd like and settings defined under a more specific section will override those in [*].

BasedOnStyles

[*]
BasedOnStyles = Style1, Style2

BasedOnStyles specifies styles that should have all of their rules enabled.

If you only want to enabled certain rules within a style, you can do so on an individual basis:

[*]
# Enables only this rule:
Style1.Rule = YES

You can also disable individual rules or change their severity level:

[*]
BasedOnStyles = Style1
Style1.Rule1 = NO
Style1.Rule2 = error

BlockIgnores

[*]
BlockIgnores = (?s) *({< file [^>]* >}.*?{</ ?file >})

BlockIgnores allow you to exclude certain block-level sections of text that don't have an associated HTML tag that could be used with SkippedScopes. See Non-Standard Markup for more information.

TokenIgnores

[*]
TokenIgnores = (\$+[^\n$]+\$+)

TokenIgnores allow you to exclude certain inline-level sections of text that don't have an associated HTML tag that could be used with IgnoredScopes. See Non-Standard Markup for more information.

Transform (v2.0)

[*]
Transform = docbook-xsl-snapshot/html/docbook.xsl

Transform specifies a version 1.0 XSL Transformation (XSLT) for converting to HTML. See Formats#XML for more information.

Search process

Heads up!

You can override the default search process by manually specifying a path using the --config option.

For example, if you'd like to use the XDG standard, you can reference the relevant environment variable:

$ vale --config="$XDG_CONFIG_HOME/vale/vale.ini"

Vale expects its configuration to be in a file named .vale.ini or _vale.ini. It'll start looking for this file in the same folder as the file that's being linted. If it can't find one, it'll search up to 6 levels up the file tree. After 6 levels, it'll look for a global configuration file in the OS equivalent of $HOME (see below).

OSSearch Locations
Windows$HOME, %UserProfile%, or %HomeDrive%%HomePath%
macOS$HOME
Linux$HOME

If more than one configuration file is present, the closest one takes precedence.