This document defines the YAML front matter emitted at the beginning of
document-level Markdown generated by miku-docx2md.
The contract is intentionally small. It identifies the converted artifact and records the conversion settings that materially affect the Markdown body.
By default, the CLI writes Markdown with front matter. Export callers may set
frontMatter: "include" to add it through the runtime API, or frontMatter:
"exclude" to omit it. The CLI may use --front-matter exclude to omit it.
CLI Markdown starts with YAML front matter by default, followed by the converted document body:
---
title: "sample.docx"
type: converted
conversion:
tool: miku-docx2md
version: "1.2.1"
unsupported_comments: exclude
---
# Document Title
| Field | Shape | Meaning |
|---|---|---|
title |
string | DOCX file name used for conversion output. |
type |
string | Stable artifact type. Current value: converted. |
conversion |
object | Tool and option metadata for this conversion. |
conversion records the settings that materially affect generated Markdown:
| Field | Shape | Meaning |
|---|---|---|
tool |
string | Tool name. Current value: miku-docx2md. |
version |
string | package.json version used by the CLI or export caller. |
unsupported_comments |
string | include or exclude, matching unsupported debug trace output. |
AI agents may use front matter to identify a converted DOCX artifact and which conversion settings were used.
Do not rely on front matter alone to reconstruct document content. The converted content lives in the Markdown body. Detailed diagnostics may appear in summary output or future sidecar artifacts rather than in front matter.