remark-mdx-frontmatter

The remark-mdx-frontmatter plugin converts YAML or TOML frontmatter into JavaScript export statements within an MDX document. This allows you to access your metadata as variables within your MDX components or application code.

import { readFile } from 'node:fs/promises'

import { compile } from '@mdx-js/mdx'
import remarkFrontmatter from 'remark-frontmatter'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'

const { value } = await compile(await readFile('example.mdx'), {
  jsx: true,
  remarkPlugins: [remarkFrontmatter, remarkMdxFrontmatter]
})
console.log(value)

To use this plugin, you must install both remark-mdx-frontmatter and its dependency remark-frontmatter. This plugin relies on the AST output produced by remark-frontmatter to function.

npm install remark-frontmatter remark-mdx-frontmatter

You can pass an options object to the plugin to customize how frontmatter is exported. The plugin also supports unist-util-mdx-define options.

The remarkMdxFrontmatter plugin transforms MDX AST by finding frontmatter nodes (like yaml or toml) and converting them into MDX named exports using unist-util-mdx-define.

If you use the name option, the parsed data is exported as a single object: export const name = { ... }.

If you do not provide a name, each top-level key in your frontmatter becomes an individual export: export const key = value.

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkMdx from 'remark-mdx'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'

// Usage in a unified pipeline
await unified()
  .use(remarkParse)
  .use(remarkMdxFrontmatter, { name: 'frontmatter' })
  .use(remarkMdx)
  .process('---\ntitle: Hello\n---
# Content')