---
title: "Frontmatter"
description: "Built-in plugin that parses a leading YAML frontmatter block into tree.frontmatter."
canonical_url: "https://comark.dev/plugins/defaults/frontmatter"
---
# Frontmatter

> Built-in plugin that parses a leading YAML frontmatter block into tree.frontmatter.

The `comark/plugins/frontmatter` plugin extracts a leading YAML frontmatter block (`---`) into `tree.frontmatter` and removes it from the markdown body before tokenization.

The plugin is **enabled by default** via `registerDefaultPlugins`. No installation or registration required.

## Usage

```mdc
---
title: Hello World
description: A sample document
---

# Hello World
```

~~~typescript
import { parseMarkdown } from 'comark'

const result = await parseMarkdown(`---
title: Hello World
---

# Hello World
`)

console.log(result.frontmatter)
// → { title: 'Hello World' }

console.log(result.nodes)
// → [ ['h1', { id: 'hello-world' }, 'Hello World'] ]
~~~

### Explicit registration

When default plugins are off, opt in with the plugin directly:

```typescript
import { parseMarkdown } from 'comark'
import frontmatter from 'comark/plugins/frontmatter'

const result = await parseMarkdown(content, {
  registerDefaultPlugins: false,
  plugins: [frontmatter()],
})
```

### Disable frontmatter parsing

Turn off all defaults (including frontmatter) so the `---` block is treated as regular markdown:

```typescript
const result = await parseMarkdown(content, { registerDefaultPlugins: false })
// result.frontmatter → {}
```

## How it works

In the `pre` hook (before markdown-exit tokenization), the plugin:

1. Detects a leading `---` … `---` block via `parseFrontmatter`
2. Parses the YAML body into `state.frontmatter`
3. Strips the frontmatter from `state.markdown`
4. Adjusts `state.parsedLines` so later nodes get correct line numbers

The core parser then copies `state.frontmatter` onto `tree.frontmatter`.

---

- [Frontmatter Syntax](https://comark.dev/syntax/frontmatter)
- [Plugins](https://comark.dev/plugins)


## Sitemap

See the full [sitemap](https://comark.dev/sitemap.md) for all pages.