X

Vale is “markup aware,” which means that it’s capable of both applying rules to and ignoring certain sections of text. This functionality is implemented through a scoping system.

A scope is specified through a selector such as paragraph.rst, which indicates that the rule applies to all paragraphs in reStructuredText files.

Here are a few examples:

comment matches all source code comments;
comment.line matches all source code line comments;
heading.md matches all Markdown headings; and
text.html matches all HTML scopes.

Vale classifies files into one of three types—markup, code, or text—that determines what scopes are available.

Within each type, there can be multiple supported formats—such as Markdown and AsciiDoc under markup. Since each format has access to the same scopes, rules are compatible across all formats within a particular type.

Markup

The default behavior for markup files is to apply rules to all non-ignored sections of the file. This means that for most rules you don’t need to specify a scope.

For rules that need to target specific sections of the file, you can use the following scopes:

Name	Description
`heading`	Matches all `h{1,...}` tags. You can specify an exact level by appending tags—for example, `heading.h1` matches all `h1` tags.
`table.header`	Matches all `th` tags.
`table.cell`	Matches all `td` tags.
`table.caption`	Matches all `caption` tags.
`figure.caption`	Matches all `figcaption` tags.
`list`	Matches all `li` tags.
`paragraph`	Matches all paragraphs (segments of text separated by two newlines).
`sentence`	Matches all sentences.
`blockquote`	Matches all `blockquote` tags.
`alt`	Matches all alt attributes.
`summary`	Matches all body text (excluding headings, code spans, code blocks, and table cells). This scope is useful for rules that need to match only sentence-level text content (such as readability scores).
`raw`	Uses the raw, unprocessed markup source instead of a specific scope. This scope is useful for regex-based rules that need to match against the original source text.

The supported formats for markup files are:

AsciiDoc
Markdown Built-in
reStructuredText
HTML Built-in
XML
Org Built-in
DITA
MDX

The formats marked as Built-in are included with Vale by default. The other formats require a third-party dependency to be installed. See each format’s documentation for more information and installation instructions.

Code

There are two code scopes: comment.line and comment.block.

See the Code documentation for more information.

Selectors

Rules may define multiple scopes by using a YAML array:

yaml
scope:
  # h1 OR h2
  - heading.h1
  - heading.h2

Any scope prefaced with ~ is negated:

yaml
scope:
  # all scopes != h2
  - ~heading.h2

You can chain multiple scopes together using &:

yaml
scope:
  # any scope that is NOT a blockquote or a heading
  - ~blockquote & ~heading

Scopes

Markup

Code

Selectors