@m2d/frontmatter

Zero-dependency front-matter plugin for md2docx to map Markdown YAML and TOML metadata to native DOCX document properties.

✨ Features

• Zero External Dependencies: Built-in quote-aware parser for YAML (:) and basic TOML (=).
• Automatic Metadata Mapping: Maps standard fields (title, author/creator, description, subject, tags/keywords, revision) directly to Word OpenXML document properties (IPropertiesOptions).
• Automated Cover Page: Generates a standalone styled title page with title, subtitle, metadata, and page break (coverPage: true).
• Metadata Info-Box / Banner: Automatically generates a styled callout blockquote or table banner (infoBox: true).
• Quote & Escape Resilient: Correctly preserves # inside strings and URLs, decodes escaped double quotes (\"), and decodes doubled single quotes ('').
• Typed Inline Arrays: Parses numbers, booleans, and quoted strings inside bracketed arrays ([item1, true, 42]).
• Pluggable Parsers: Seamlessly inject dedicated parsers (e.g. smol-toml or yaml) for complex nested tables, multi-line strings, or full specifications.

📦 Installation

pnpm add @m2d/frontmatter

🚀 Usage

Basic Example (Zero Configuration)

import { toDocx } from "@m2d/core";
import { frontmatterPlugin } from "@m2d/frontmatter";

const docxBlob = await toDocx(
  mdast,
  {},
  {
    plugins: [frontmatterPlugin()],
  },
);

Advanced TOML Support (via Custom Parser)

For complex TOML documents containing tables ([metadata]), dates, or multi-line strings, install a dedicated parser like smol-toml and inject it into the plugin:

pnpm add smol-toml

import { parse as parseToml } from "smol-toml";
import { frontmatterPlugin, parseFrontmatter } from "@m2d/frontmatter";

const plugin = frontmatterPlugin(undefined, {
  parser: (raw, type) =>
    type === "toml" ? parseToml(raw) : parseFrontmatter(raw, type),
});

Advanced YAML Support (via yaml)

Similarly, if you need full YAML 1.2 spec features (anchors &, aliases *, or complex folded blocks):

pnpm add yaml

import { parse as parseYaml } from "yaml";
import { frontmatterPlugin } from "@m2d/frontmatter";

const plugin = frontmatterPlugin(undefined, {
  parser: (raw) => parseYaml(raw),
});

License

This library is licensed under the MIT open-source license.