Docs
Topics
Scopes

Scopes

Learn about Vale's advanced markup-specific scoping system.

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:

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
Styles Actions