# 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](/formats/asciidoc.md)
* [Markdown](/formats/markdown.md) Built-in
* [reStructuredText](/formats/restructuredtext.md)
* [HTML](/formats/html.md) Built-in
* [XML](/formats/xml.md)
* [Org](/formats/org.md) Built-in
* [DITA](/formats/dita.md)
* [MDX](/formats/mdx.md)

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](/formats/code.md) 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vale.sh/topics/scopes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.