Frontmatter & Document Metadata

Modern technical documents and markdown files commonly include metadata headers (frontmatter) for titles, authors, keywords, and publication dates.

md2docx includes first-class frontmatter extraction powered by @m2d/frontmatter. When enabled, frontmatter headers are parsed, removed from the generated Word document body, and written directly into native OpenXML Document Properties (Core & Extended file properties).

🚀 Quick ExampleCopy Anchor Link

---
title: System Architecture Specification
author: Jane Doe
subject: Microservices Migration Plan
keywords: [cloud, architecture, kubernetes, openxml]
company: Acme Corp
category: Engineering Specs
---

# 1. Executive Summary

This document outlines the proposed system architecture...

When compiled:

1. The frontmatter block is stripped from the document body so it does not render as raw text.
2. The Word document file properties (visible in File → Info in Microsoft Word) are automatically populated:
   • Title: System Architecture Specification
   • Author / Creator: Jane Doe
   • Subject: Microservices Migration Plan
   • Keywords: cloud, architecture, kubernetes, openxml
   • Company: Acme Corp

📋 Standard Metadata Key MappingsCopy Anchor Link

The plugin automatically maps common Markdown and SSG metadata keys to Microsoft Word OpenXML properties:

⚙️ Configuration & OptionsCopy Anchor Link

frontmatterPlugin accepts options to customize parsing and mapping behavior:

import { md2docx } from "@m2d/md2docx";
import { frontmatterPlugin } from "@m2d/frontmatter";

const docxBlob = await md2docx(markdown, {
  plugins: [
    frontmatterPlugin({
      // Strip frontmatter from output document (default: true)
      strip: true,

      // Custom metadata transformer
      transform: (rawMetadata, defaultProps) => {
        return {
          ...defaultProps,
          title: `[CONFIDENTIAL] ${defaultProps.title ?? "Untitled"}`,
          company: rawMetadata.org ?? defaultProps.company,
        };
      },
    }),
  ],
});

🧩 Advanced Parsers (Full YAML & TOML Specs)Copy Anchor Link

By default, @m2d/frontmatter includes a lightweight, zero-dependency parser that handles:

• Basic and quoted scalars (including double quotes and doubled single quotes '').
• Comments (#) with quote-awareness.
• Flow arrays (keywords: [alpha, beta, "gamma delta"]).
• Indented list sequences (- item1\n- item2).
• Basic TOML key-value pairs (=).

If your project uses complex YAML anchors, multi-line folded blocks (>), or advanced TOML tables, you can inject full-spec parsers via options.parser:

Using yaml (Full YAML 1.2 Support)Copy Anchor Link

pnpm add yaml

import YAML from "yaml";
import { frontmatterPlugin } from "@m2d/frontmatter";

const plugin = frontmatterPlugin({
  parser: (raw: string, type: "yaml" | "toml") => {
    if (type === "yaml") {
      return YAML.parse(raw);
    }
    return {};
  },
});

Using smol-toml (Full TOML Support)Copy Anchor Link

pnpm add smol-toml

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

const plugin = frontmatterPlugin({
  parser: (raw: string, type: "yaml" | "toml") => {
    if (type === "toml") {
      return parseToml(raw);
    }
    return {};
  },
});

🔒 Security & Prototype Pollution ProtectionCopy Anchor Link

@m2d/frontmatter strictly protects against object prototype poisoning. Keys matching __proto__, constructor, or prototype are discarded during extraction, ensuring untrusted markdown inputs cannot pollute global runtime scopes.