# 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](#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`        | <p>Matches all <code>h{1,...}</code> tags. You can specify an exact level by<br>appending tags—for example, <code>heading.h1</code> matches all <code>h1</code> tags.</p>                                           |
| `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`        | <p>Matches all body text (excluding headings, code spans, code blocks, and<br>table cells). This scope is useful for rules that need to match only<br>sentence-level text content (such as readability scores).</p> |
| `raw`            | <p>Uses the raw, unprocessed markup source instead of a specific scope. This<br>scope is useful for regex-based rules that need to match against the<br>original source text.</p>                                   |

The supported formats for markup files are:

* [AsciiDoc](https://docs.vale.sh/formats/asciidoc)
* [Markdown](https://docs.vale.sh/formats/markdown) Built-in
* [reStructuredText](https://docs.vale.sh/formats/restructuredtext)
* [HTML](https://docs.vale.sh/formats/html) Built-in
* [XML](https://docs.vale.sh/formats/xml)
* [Org](https://docs.vale.sh/formats/org) Built-in
* [DITA](https://docs.vale.sh/formats/dita)
* [MDX](https://docs.vale.sh/formats/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](#code)

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

See the [Code](https://docs.vale.sh/formats/code) documentation for more information.

## [Selectors](#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
```
