satteri-mdx-frontmatter
satteri-mdx-frontmatter
Sätteri MDAST plugin that turns a document’s frontmatter into an MDX
export, a port of
remark-mdx-frontmatter.
Sätteri parses frontmatter on its own and hands the raw block back to you on the compile result, but
it never reaches the compiled module. Write this:
---
title: Hello
---
# {frontmatter.title}
and without this plugin the compiled JavaScript refers to a frontmatter that is not declared
anywhere — the module throws the moment it renders. This plugin prepends
export const frontmatter = {"title": "Hello"};, so the expression resolves and anything importing
the compiled module can read the metadata too.
Install
npm install satteri-mdx-frontmatter
YAML works out of the box. TOML does not: +++ blocks need a parser passed in, see
options.parsers.
Use
import { mdxToJs } from "satteri";
import { satteriMdxFrontmatter } from "satteri-mdx-frontmatter";
const { code } = await mdxToJs("---\ntitle: Hello\n---\n\n# {frontmatter.title}\n", {
mdastPlugins: [satteriMdxFrontmatter()],
});
// export const frontmatter = { "title": "Hello" };
// …
// function _createMdxContent(props) { … frontmatter.title … }
It runs at the MDAST stage, so pass it to mdastPlugins.
With Astro 7:
// astro.config.mjs
import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";
import { satteriMdxFrontmatter } from "satteri-mdx-frontmatter";
export default defineConfig({
markdown: {
processor: satteri({
mdastPlugins: [satteriMdxFrontmatter()],
}),
},
});
API
satteriMdxFrontmatter(options?)
options.name
string, default "frontmatter". The identifier the data is exported as. It must be a plain
JavaScript identifier (/^[A-Za-z_$][A-Za-z0-9_$]*$/) and not a reserved word; anything else throws
immediately rather than emitting a module that will not parse.
options.parsers
Record<string, (value: string) => unknown>, default {}. A parser per frontmatter node type:
yaml for --- … --- blocks, toml for +++ … +++ blocks. The parser receives the raw text
between the fences and returns the data.
A frontmatter block whose type has no registered parser throws. Parser errors are not caught — bad
frontmatter fails the build, as it does with remark-mdx-frontmatter.
What gets emitted
The parsed value is written out as a JavaScript expression, so the export is real data rather than a
string:
| Frontmatter | Emitted |
|---|---|
title: Hello |
export const frontmatter = { "title": "Hello" }; |
| a bare scalar | export const frontmatter = "just a string"; |
| a sequence | export const frontmatter = ["a", "b"]; |
| an empty block | export const frontmatter = null; (whatever the parser returns) |
a parser returning undefined |
export const frontmatter = undefined; |
Serialisation is deliberately not JSON.stringify:
- a
__proto__key is emitted as a computed key, so frontmatter cannot reassign the exported
object’s prototype; NaNandInfinitysurvive instead of collapsing tonull;Datevalues becomenew Date("…")rather than a string;BigIntvalues become bigint literals;undefinedis expressible, both at the top level and as a whole value.
Otherwise JSON’s rules hold: undefined object values are dropped, undefined array items become
null, and circular data is an error — thrown with a clear message rather than overflowing the
stack.
Differences from remark-mdx-frontmatter
TOML needs a parser passed in
remark-mdx-frontmatter depends on both yaml and
toml. This package depends on yaml only, so YAML works
with no configuration and TOML needs a parser through options.parsers. You pay for a TOML parser
only if you use TOML, and you can still swap the YAML implementation by passing your own.
No export when there is no frontmatter
remark-mdx-frontmatter operates on the document root, so it always defines the export — falling
back to its default option, or undefined. Sätteri’s MDAST visitor API subscribes to node types
and has no root or document hook, so this plugin only runs when a yaml or toml node exists. A
document with no frontmatter gets no export at all, and {frontmatter.title} in such a document
still fails.
Because that fallback is unreachable, the default option is not implemented rather than being
offered and silently ignored.
No named-exports mode
Early versions of remark-mdx-frontmatter could export each top-level key as its own binding. v5
does not — name defaults to "frontmatter" and there is no way to opt out — and neither does this
plugin. Destructure at the use site instead.
No unist-util-mdx-define options
remark-mdx-frontmatter forwards export ('module' | 'namespace' | false) and conflict
('skip' | 'throw' | 'warn') to
unist-util-mdx-define. This plugin always
emits a module-level export const and does not detect name conflicts with a binding the document
declares itself; such a conflict surfaces as a JavaScript parse error from Sätteri.
Serialisation is narrower
remark-mdx-frontmatter builds an ESTree expression with
estree-util-value-to-estree, which
also handles RegExp, Map, Set, URL, typed arrays, and shared references via
preserveReferences. This plugin emits source text and covers JSON-like data plus Date and
BigInt. A repeated reference is written out twice rather than being made identical again; anything
else is serialised as a plain object, the way JSON would.
Markdown compiles are left alone
The same plugin can sit in a config shared between Markdown and MDX. In a plain Markdown compile
there is no module to export into, so the plugin does nothing at all — it does not parse the block
and does not require a parser to be registered.
Licence
MIT © Ashish Vaghela