Markdown to Word: Native Style Mapping and the Inline-Format Downgrade List

The journal wants .docx. Editorial accepts Word only. The client's procurement system rejects anything that isn't Office. Your Markdown draft is done, and the last mile is a format conversion. The reverse direction (Word to Markdown) is migration; this one is delivery — the goal is not "the content is there" but "the recipient can keep editing, navigate by styles, and feed it into their pipeline".

Two routes: pandoc in one command (batch, local), or the Markdown to Word tool entirely in the browser (paste, convert, download — the file never leaves the machine).

"Editable" beats "looks right"

The tell of a bad converter: headings come out as 22pt bold text that looks like a heading, but in Word's style panel it's "Normal". The damage is immediate:

• the recipient opens the navigation pane and the outline is empty — Word builds it from Heading styles;
• changing the body font means hand-selecting paragraphs, because nothing is style-bound;
• auto-generating a table of contents finds zero headings.

The acceptance test for a conversion is one line: open the style panel and check that # landed on "Heading 1". Both routes discussed here pass, because they emit native Word styles rather than visual imitations.

Route one: pandoc (for batch delivery)

pandoc draft.md -o deliverable.docx

Two parameters matter for delivery work: --reference-doc=template.docx applies your house template (fonts, headers, cover styles); --toc generates a table of contents page. Wrap it in a shell loop for batches. Pandoc's docx output is the best open-source option — for serious delivery pipelines, it's the default.

Route two: in-browser local conversion (paste and go)

For the occasional one-off, or machines where you can't install anything (locked-down corporate laptops, a client's computer), the browser route wins:

1. Open the Markdown to Word tool;
2. Paste the Markdown source;
3. Convert → download the .docx.

Parsing and packaging happen inside your browser process; it works offline. For the reverse (a Word file that needs to enter your md repository), the Word to Markdown tool runs equally locally.

Style mapping reference

The inline-format downgrade list (read before relying on it)

The browser tool currently degrades these inline Markdown constructs to plain text — a deliberate tradeoff, not a bug, but you should know it:

• **bold**, *italic*, `inline code` → plain text (markers stripped, words kept);
• images ![]() and links [text](url) → text kept, URLs and image content dropped;
• nested lists → promoted to the same level.

So its home turf is prose delivery: proposals, specs, weekly reports, article drafts. For documents where inline formatting and images are load-bearing, use pandoc, or plan a manual formatting pass. The decision rule: the higher the density of inline formats and images, the more you should lean on pandoc.

Implementer's note

The browser implementation walks marked's lexer directly into docx-library objects, token by token — deliberately skipping the more common "marked → HTML → docx" hop. One less layer of semantic approximation: heading depths, table structure, and code-block boundaries come straight from the lexer. The docx library (Packer/Paragraph/Table) is dynamically imported — nothing loads until you actually convert. Code-block shading is set via shading with the font pinned to Consolas, so CJK-locale Word installs can't drop it into a serif default. Blockquotes intentionally render as "italics + indent" rather than Word's Quote style: the Quote style's appearance varies too much across Word versions, and a visual approximation is more predictable. The inline downgrade is the current architecture's honest boundary — the inline layer handles plain text only; splitting inline runs would mean rewriting the layer, and bold/italic alone don't justify that risk versus clearly marking the edge and pointing heavy formatting at pandoc. The creator metadata reads ToolVault, traceable in document properties.

FAQ

The recipient says it won't open / shows garbled text?

First confirm the extension is .docx (OOXML). Word 2007+, WPS, and Microsoft 365 all read it; ancient Word 2003 needs the compatibility pack — a boundary shared by every modern converter.

How do I apply our corporate fonts and headers?

Pandoc route: --reference-doc=company-template.docx — its style definitions are inherited. The browser route emits Word's default styles; swapping to house styles is a one-click "Design → Style Set" for the recipient — another dividend of native styles over visual imitation.

Why no images?

The browser tool targets prose delivery. Images involve binary packaging and size tradeoffs that pandoc already solves well (auto-extraction and embedding). For image-heavy documents, pandoc is the honest recommendation.

Can it generate a table of contents?

The document uses native Heading styles, so the recipient generates one in Word via References → Table of Contents — more flexible than baking a ToC page at conversion time, since page numbers depend on their final layout.

These delivery notes come from building the bidirectional document converters at ToolVault; the downgrade list is the code's actual boundary, not marketing hedging.

Field note

The lexer-direct path wasn't architectural purism — testing caught the HTML hop misreading paragraphs that begin with 1. as ordered lists (the classic ordered-list boundary ambiguity), while the token stream preserved the "this is a paragraph" first-hand judgment. One less representation, one less class of ambiguity.