Front Matter

Learn how Vale handles front matter.

Front matter is linted in Markdown and its dialects (MDX, MyST, Quarto, R Markdown), AsciiDoc, reStructuredText, Org, Typst, and QDoc files.

There are 3 supported front matter types – YAML, TOML, and JSON. Each is recognized by the delimiters that open and close it:

YAML

Opening and closing --- lines:

---
name: "frontmatter"
---
rest of the content

Or an opening ---yaml line with a closing ---:

---yaml
name: "frontmatter"
---
rest of the content

TOML

Opening and closing +++ lines:

+++
name = "frontmatter"
+++
rest of the content

Or an opening ---toml line with a closing ---:

---toml
name = "frontmatter"
---
rest of the content

JSON

Opening and closing ;;; lines:

;;;
{
    "name": "frontmatter"
}
;;;
rest of the content

Or an opening ---json line with a closing ---:

---json
{
    "name": "frontmatter"
}
---
rest of the content

A bare JSON object followed by an empty line also works:

{
    "name": "frontmatter"
}

rest of the content

Each field is dynamically assigned its own scope, allowing you to write rules that target specific ones:

---
title: 'My document'
description: "A short summary of the document's purpose."
author: 'John Doe'
---

Using the example above, the generated scopes would be text.frontmatter.title, text.frontmatter.description, and text.frontmatter.author.

A rule can then use these in its scope: field:

extends: capitalization
message: "'%s' should be in title case"
level: warning
scope: text.frontmatter.title

This rule would then only be applied to the title field in the front matter.

Only string-valued fields are linted; a list or a nested map is left alone. A field can be excluded by naming its scope in IgnoredScopes.