remark-mdx-frontmatter

remark-mdx-frontmatter is a remark plugin that reads the frontmatter node produced by remark-frontmatter and turns it into a first-class JavaScript export inside compiled MDX. Instead of leaving frontmatter as inert metadata, it hands the parsed YAML or TOML block to your MDX component as a frontmatter export (or any name you choose), ready to import and render alongside the page content.

The plugin ships as a single focused module built on the unified/remark ecosystem, delegating the actual parsing to the yaml and toml packages and the export wiring to unist-util-mdx-define. It is a common building block in MDX-based static site generators and documentation tools that need typed access to page metadata (titles, dates, tags) without a separate data-loading step.

What You Get

• Automatic YAML and TOML frontmatter parsing
• A configurable export name for the parsed frontmatter object
• A configurable default value when a document has no frontmatter
• Pluggable custom parsers per frontmatter node type
• TypeScript type definitions for options and output shipped with the package

Common Use Cases

• Exposing blog post metadata (title, date, tags) as an importable constant in a static site generator
• Building MDX-based documentation sites that render frontmatter fields in page headers
• Feeding parsed frontmatter into layout components without a separate content-loading pipeline
• Supporting both YAML and TOML frontmatter conventions in the same MDX pipeline

Under The Hood

Architecture The entire implementation lives in one file, src/remark-mdx-frontmatter.ts, which exports a single unified Plugin factory. The returned transformer walks the mdast tree’s top-level children looking for a node whose type matches a registered parser key (yaml or toml by default), extracts its raw literal value, and hands it to the matching parser function. Rather than manipulating the MDX/estree output itself, the plugin delegates all export-wiring — inserting the parsed data as a named export into the compiled module — to the author’s separate unist-util-mdx-define package, keeping this module’s own surface area extremely thin. This composition-over-implementation approach means the plugin’s only real responsibility is locating and parsing the frontmatter node; everything downstream is handled by well-scoped collaborator packages, so a change to how MDX exports are defined would only ripple through unist-util-mdx-define, not this repo.

Tech Stack Written in strict TypeScript (tsconfig targets ES2022 with node16 module resolution and full declaration output), the package builds via tsc —build and ships as a pure ESM module (type: module). Runtime dependencies are narrowly scoped: yaml and toml handle the two supported frontmatter formats, estree-util-value-to-estree converts parsed values into estree AST nodes, unified provides the plugin type contract, and unist-util-mdx-define performs the actual export injection. The dev toolchain layers @remcohaszing/eslint and Prettier for style, remark-cli with remark-preset-remcohaszing to lint the project’s own markdown, c8 for coverage, and snapshot-fixtures to drive fixture-based tests against @mdx-js/mdx and mdast-util-mdx. CI (GitHub Actions) runs eslint, prettier —check, remark —frail, npm pack, and the test suite across a Node.js version matrix, with coverage uploaded to Codecov.

Code Quality Testing is snapshot/fixture-based: src/remark-mdx-frontmatter.test.ts uses snapshot-fixtures’ testFixturesDirectory to compile each of the nine fixtures/ cases (named export, default value, TOML input, custom parser, null/undefined handling, and more) through @mdx-js/mdx and assert the output against a checked-in expected.jsx. The .c8rc.json config enforces full coverage on every test run, and results are reported via both a JUnit reporter and Codecov. TypeScript runs in strict mode with noImplicitAny, and the public options interface (RemarkMdxFrontmatterOptions) is fully typed and documented with JSDoc. Linting is enforced through a shared @remcohaszing/eslint config plus a dedicated remark lint pass over the project’s own Markdown, all gated in CI — there is no evidence of untested code paths or loose typing anywhere in the small codebase.

API Design The public API is a single default-exported plugin function taking an optional options object (default, name, parsers, plus whatever unist-util-mdx-define accepts), so the common case is just remarkPlugins: [remarkFrontmatter, remarkMdxFrontmatter] with zero configuration — frontmatter becomes available as a frontmatter export automatically. Option names (default, name, parsers) follow the conventions of similar remark/rehype plugins, and the README documents each with defaults and short descriptions plus a runnable before/after example. Nothing about the approach is novel — parsing frontmatter and injecting an export is a well-trodden pattern in the MDX ecosystem, and this plugin’s main contribution is doing that one thing cleanly while reusing the author’s own unist-util-mdx-define rather than reinventing export-wiring — but the low-boilerplate integration and consistent naming make it easy to adopt without reading source.