Skip to content

Frontmatter

Use frontmatter to apply page-level metadata to Markdoc documents, like title and description. Markdoc doesn't have an opinion about how you format your frontmatter, you can use YAML, TOML, JSON, GraphQL—pretty much any data format you want.

Examples

While not a comprehensive list, the examples below give you an idea of how you can structure frontmatter in various formats.

YAML

---
title: Authoring in Markdoc
description: Quickly author amazing content with Markdoc syntax, a superset of Markdown.
date: 2022-04-01
---

TOML

---
title       = "Authoring in Markdoc"
description = "Quickly author amazing content with Markdoc syntax, a superset of Markdown."
date        = "2022-04-01"
---

JSON

---
{
  "title": "Authoring in Markdown",
  "description": "Quickly author amazing content with Markdoc syntax, a superset of Markdown.",
  "date": "2022-04-01"
}
---

GraphQL

---
{
  page {
    title
    description
    date
  }
}
---

Access frontmatter values

To access frontmatter content in your document, you have to pass the values to Markdoc as variables.

Parse the document

Parse your document to access the frontmatter content:

const doc = `
---
title: My title
---

# {% $frontmatter.title %} 
`;

const ast = Markdoc.parse(doc);

Parse the frontmatter

Parse the frontmatter attribute using your preferred format and pass it in the variables field of your config object.

import yaml from 'js-yaml'; // or 'toml', etc.

const frontmatter = ast.attributes.frontmatter
  ? yaml.load(ast.attributes.frontmatter)
  : {};

/** @type {import('@markdoc/markdoc').Config} */
const config = {
  variables: {
    frontmatter
  }
};

Use frontmatter values

After passing the parsed frontmatter to variables, you can access the values using $frontmatter:

# {% $frontmatter.title %}

Frontmatter