Skip to content

Commit 909cd94

Browse files
committed
feat(@m2d/frontmatter): ✨ implement quote-aware YAML parser and optional smol-toml support
1 parent a178541 commit 909cd94

7 files changed

Lines changed: 577 additions & 36 deletions

File tree

‎.changeset/frontmatter-support.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
3+
"@m2d/core": minor
4+
"@m2d/frontmatter": minor
5+
---
6+
7+
- Add native front-matter metadata extraction to map Markdown YAML metadata directly to Word document properties (`title`, `creator`, `description`, `subject`, `keywords`).
8+
- Add dedicated `@m2d/frontmatter` plugin with YAML/TOML support and custom transform options.
9+
- Deprecate `IPlugin.root`: Use `IPlugin.preprocess(tree, definitions, docxProps)` instead to inspect the AST and configure document-level properties.

‎packages/frontmatter/README.md‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,35 +19,58 @@
1919
<img alt="license" src="https://img.shields.io/npm/l/@m2d/frontmatter" />
2020
</p>
2121

22-
> @m2d/frontmatter:
22+
> Front-matter plugin for md2docx to map Markdown YAML/TOML metadata to native DOCX document properties.
2323
2424
---
2525

26-
## ✨ Why @m2d/frontmatter?
26+
## ✨ Features
2727

28-
-
29-
-
28+
- **Automatic Metadata Mapping:** Maps standard Markdown front-matter fields (`title`, `author`/`creator`, `description`, `subject`, `tags`/`keywords`, `revision`) directly to Word OpenXML document properties (`IPropertiesOptions`).
29+
- **Custom Properties Support:** Extra front-matter attributes (e.g. `department`, `status`, `date`) are preserved as Word custom document properties.
30+
- **YAML & TOML Support:** Parses both YAML (`--- ... ---`) and TOML (`+++ ... +++`) front-matter blocks.
31+
- **Custom Transformers:** Full control via custom parser and transform callbacks.
3032

3133
---
3234

3335
## 📦 Installation
3436

3537
```bash
36-
$ pnpm add @m2d/frontmatter
38+
pnpm add @m2d/frontmatter
3739
```
3840

39-
**_or_**
41+
---
4042

41-
```bash
42-
$ npm install @m2d/frontmatter
43+
## 🚀 Usage
44+
45+
### Basic Example
46+
47+
```typescript
48+
import { toDocx } from "@m2d/core";
49+
import { frontmatterPlugin } from "@m2d/frontmatter";
50+
51+
const docxBlob = await toDocx(
52+
mdast,
53+
{},
54+
{
55+
plugins: [frontmatterPlugin()],
56+
},
57+
);
4358
```
4459

45-
**_or_**
60+
### Custom Transform Example
4661

47-
```bash
48-
$ yarn add @m2d/frontmatter
62+
```typescript
63+
import { frontmatterPlugin } from "@m2d/frontmatter";
64+
65+
const plugin = frontmatterPlugin(undefined, {
66+
transform: (data, docxProps) => {
67+
docxProps.title = `[Confidential] ${data.title}`;
68+
docxProps.subject = String(data.category ?? "General");
69+
},
70+
});
4971
```
5072

73+
---
5174

5275
## License
5376

‎packages/frontmatter/package.json‎

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
"access": "public",
88
"provenance": true
99
},
10-
"description": "",
10+
"description": "Front-matter plugin for md2docx to map Markdown YAML/TOML metadata to native DOCX document properties.",
1111
"license": "MIT",
1212
"main": "./dist/index.js",
1313
"module": "./dist/index.mjs",
@@ -37,19 +37,36 @@
3737
"dist/**"
3838
],
3939
"scripts": {
40-
"build": "tsup && gzip -c dist/index.js | wc -c",
40+
"build": "tsup",
4141
"clean": "rm -rf dist",
4242
"dev": "tsup --watch"
4343
},
44+
"dependencies": {
45+
"@m2d/core": "workspace:*"
46+
},
47+
"peerDependencies": {
48+
"docx": "^9.3.0",
49+
"smol-toml": "^1.3.0"
50+
},
51+
"peerDependenciesMeta": {
52+
"smol-toml": {
53+
"optional": true
54+
}
55+
},
4456
"devDependencies": {
57+
"@types/mdast": "^4.0.4",
4558
"@types/node": "latest",
59+
"docx": "^9.13.0",
4660
"tsup": "latest",
4761
"typescript": "latest"
4862
},
4963
"forge": {
50-
"aliases": [],
51-
"icon": "LibraryBig",
52-
"description": ""
64+
"aliases": [
65+
"@md2docx/frontmatter",
66+
"@mdast2docx/frontmatter"
67+
],
68+
"icon": "FileText",
69+
"description": "Front-matter Metadata Plugin"
5370
},
5471
"funding": [
5572
{
@@ -63,6 +80,17 @@
6380
],
6481
"keywords": [
6582
"@m2d/frontmatter",
83+
"frontmatter",
84+
"yaml",
85+
"toml",
86+
"metadata",
87+
"docx",
88+
"markdown-to-docx",
89+
"mdast-to-docx",
90+
"md2docx",
91+
"mdast2docx",
92+
"m2d",
93+
"mayank1513",
6694
"turboforge"
6795
]
6896
}
Lines changed: 166 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,171 @@
11
/** biome-ignore-all lint/suspicious/noExplicitAny: Use of any is ok for test files */
22

3-
import { describe, test } from "vitest";
3+
import { describe, expect, test } from "vitest";
4+
import {
5+
extractFrontmatterNode,
6+
frontmatterPlugin,
7+
parseFrontmatter,
8+
} from "./frontmatter";
49

5-
describe("m2dFrontmatter", () => {
6-
test("should pass", ({ expect }) => {
7-
expect(true).toBe(true);
10+
describe("parseFrontmatter", () => {
11+
test("should parse YAML with lists, strings, and numbers", () => {
12+
const raw = `
13+
title: "Modern Architecture"
14+
author: "Mayank Chaudhari"
15+
revision: 3
16+
published: true
17+
tags:
18+
- docx
19+
- markdown
20+
- typescript
21+
`;
22+
const res = parseFrontmatter(raw);
23+
expect(res.title).toBe("Modern Architecture");
24+
expect(res.author).toBe("Mayank Chaudhari");
25+
expect(res.revision).toBe(3);
26+
expect(res.published).toBe(true);
27+
expect(res.tags).toEqual(["docx", "markdown", "typescript"]);
28+
});
29+
30+
test("should preserve '#' in quotes and URLs without comment truncation", () => {
31+
const raw = `
32+
title: "C# Guide"
33+
url: "https://example.com/#section"
34+
commented: Value # this is actual comment
35+
`;
36+
const res = parseFrontmatter(raw);
37+
expect(res.title).toBe("C# Guide");
38+
expect(res.url).toBe("https://example.com/#section");
39+
expect(res.commented).toBe("Value");
40+
});
41+
42+
test("should parse inline bracketed arrays with quoted commas", () => {
43+
const raw = `keywords: ["React, Next.js", TypeScript]`;
44+
const res = parseFrontmatter(raw);
45+
expect(res.keywords).toEqual(["React, Next.js", "TypeScript"]);
46+
});
47+
48+
test("should parse TOML front-matter when smol-toml or custom parser is present", () => {
49+
const raw = `title = "TOML Title"`;
50+
const res = parseFrontmatter(raw, "toml");
51+
// If smol-toml is hoisted, it parses successfully; otherwise returns empty object
52+
if (res.title) {
53+
expect(res.title).toBe("TOML Title");
54+
} else {
55+
expect(res).toEqual({});
56+
}
57+
});
58+
59+
test("should parse TOML when custom parser is provided", () => {
60+
const raw = `title = "TOML Title"`;
61+
const plugin = frontmatterPlugin(undefined, {
62+
parser: (input) => ({
63+
title: input.includes("TOML") ? "Custom TOML" : "",
64+
}),
65+
});
66+
67+
const docxProps: any = {};
68+
const ast: any = {
69+
type: "root",
70+
children: [{ type: "toml", value: raw }],
71+
};
72+
73+
plugin.preprocess?.(ast, {}, docxProps);
74+
expect(docxProps.title).toBe("Custom TOML");
75+
});
76+
});
77+
78+
describe("extractFrontmatterNode", () => {
79+
test("should find yaml or toml node in AST", () => {
80+
const ast: any = {
81+
type: "root",
82+
children: [{ type: "yaml", value: "title: Test" }],
83+
};
84+
const node = extractFrontmatterNode(ast);
85+
expect(node?.value).toBe("title: Test");
86+
});
87+
});
88+
89+
describe("frontmatterPlugin metadata normalization", () => {
90+
test("should populate document properties from AST during preprocess", () => {
91+
const plugin = frontmatterPlugin();
92+
const props: any = {};
93+
const ast: any = {
94+
type: "root",
95+
children: [
96+
{
97+
type: "yaml",
98+
value: `
99+
title: "Plugin Title"
100+
author: "Plugin Author"
101+
tags: ["Docx, OpenXML", Markdown]
102+
department: "Engineering"
103+
`,
104+
},
105+
],
106+
};
107+
108+
plugin.preprocess?.(ast, {}, props);
109+
110+
expect(props.title).toBe("Plugin Title");
111+
expect(props.creator).toBe("Plugin Author");
112+
expect(props.keywords).toBe("Docx, OpenXML, Markdown");
113+
expect(props.customProperties).toContainEqual({
114+
name: "department",
115+
value: "Engineering",
116+
});
117+
});
118+
119+
test("should skip null, undefined, objects, and forbidden prototype keys", () => {
120+
const plugin = frontmatterPlugin(undefined, {
121+
parser: () => ({
122+
title: "Valid",
123+
__proto__: "evil",
124+
nested: { child: true },
125+
emptyVal: null,
126+
undefVal: undefined,
127+
}),
128+
});
129+
const props: any = {};
130+
const ast: any = {
131+
type: "root",
132+
children: [
133+
{
134+
type: "yaml",
135+
value: "title: Valid",
136+
},
137+
],
138+
};
139+
140+
plugin.preprocess?.(ast, {}, props);
141+
142+
expect(props.title).toBe("Valid");
143+
expect(Object.getPrototypeOf(props)).not.toBe("evil");
144+
expect(
145+
props.customProperties?.some((p: any) => p.name === "__proto__"),
146+
).toBeFalsy();
147+
expect(
148+
props.customProperties?.some((p: any) => p.name === "nested"),
149+
).toBeFalsy();
150+
expect(
151+
props.customProperties?.some((p: any) => p.name === "emptyVal"),
152+
).toBeFalsy();
153+
});
154+
155+
test("should support custom transform function", () => {
156+
const plugin = frontmatterPlugin(undefined, {
157+
transform: (data, props) => {
158+
props.title = `Transformed: ${data.title}`;
159+
},
160+
});
161+
162+
const props: any = {};
163+
const ast: any = {
164+
type: "root",
165+
children: [{ type: "yaml", value: "title: Custom" }],
166+
};
167+
168+
plugin.preprocess?.(ast, {}, props);
169+
expect(props.title).toBe("Transformed: Custom");
8170
});
9171
});

0 commit comments

Comments
 (0)