Configuration

Control what Vale lints, how it lints, and where it lints.

Config file #

Vale’s configuration is read from a .vale.ini file. This file is INI-formatted and consists of three sections: core settings, format associations, and format-specific settings:

# 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 #

# 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.

As of v3.0.0, Vale supports a default StylesPath. The location of this path depends on your operating system:

(Run the vale ls-dirs command to see the exact locations on your system.)

Packages #

The list of packages to install to the StylesPath.

After running the sync command, the styles will be added to the active StylesPath, and any configuration files will be added to StylesPath/.config according to the order in which they were loaded.

See Packages for more information and usage examples.

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 #

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.

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. Note that this is merely an extension-level substitution and is not a means of adding support for a new file type.

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 enable 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 allow you to exclude certain block-level sections of text that don’t have an associated HTML tag that could be used with SkippedScopes.

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

The basic idea is to capture the entire block in the first grouping. See regex101 for a more thorough explanation.

You can also define more than one block by using a list (the \ allows for line breaks):

BlockIgnores = (?s) *({< output >}.*?{< ?/ ?output >}), \
(?s) *({< highlight .* >}.*?{< ?/ ?highlight >})

CommentDelimiters #

CommentDelimiters allow you to override standard, HTML comment delimiters (<!-- -->).

Custom comment delimiters are useful when using non-standard markup which do not allow HTML-style comments.

[formats]
mdx = md

[*.mdx]
BasedOnStyles = Vale

CommentDelimiters = {/*, */}

When CommentDelimiters are set, you can take full advantage of markup-based configuration to enable or disable specific rules within a section.

For instance, when using MDX:

{/* vale off */}

This is some text ACT test

This is some text ACT test

{/* vale on */}

{/* vale vale.Redundancy = NO */}

This is some text ACT test

{/* vale vale.Redundancy = YES */}

TokenIgnores #

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.

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

The basic idea is to capture the entire inline-level section in the first grouping. See regex101 for a more thorough explanation.

Transform #

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

Transform specifies a version 1.0 XSL Transformation (XSLT) for converting to HTML.

Markup-based configuration #

You can use selective, in-text configuration through markup comments in certain formats. The follow sections describe the comment style required for each supported format.

Markdown & HTML #

Markdown and HTML use HTML-style comments:

<!-- vale off -->

This is some text

more text here...

<!-- vale on -->

<!-- vale Style.Rule = NO -->

This is some text

<!-- vale Style.Rule = YES -->

reStructuredText #

reStructuredText uses its own comment style:

.. vale off

This is some text

.. vale on

Org Mode #

Org Mode uses its own comment style:

# vale off

This is some text

# vale on

AsciiDoc #

AsciiDoc uses HTML-style comments with its pass-through functionality:

pass:[<!-- vale Microsoft.GenderBias = NO -->]

This steward is ignored.

pass:[<!-- vale Microsoft.GenderBias = YES -->]

This is a steward that raises an alert.

Search process #

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 the file tree.

If no ancestor of the current directory has a configuration file, Vale will use a global configuration file (see below).

Global configuration #

In addition to project-specific configurations, Vale also supports a global configuration file and StylesPath. The expected location of the global configuration depends on your operating system:

(Run the vale ls-dirs command to see the exact locations on your system.)

This is different from the other config-defining options (--config, VALE_CONFIG_PATH, etc.) in that it’s loaded in addition to, rather than instead of, any other configuration sources.

In other words, this config file is always loaded and is read after any other sources to allow for project-agnostic customization.