Markdown to Word and Back: The DOCX Conversion Guide
How to convert markdown to Word and Word to markdown with Pandoc — reference-doc styling, what survives DOCX conversion, extracting images, track changes, and the docx to markdown gotchas.
Short answer: Use Pandoc. To go markdown to Word, run pandoc input.md -o output.docx. To go the other way — Word to markdown, or any docx to markdown — run pandoc input.docx -o output.md. Add --reference-doc=custom.docx to control Word styling on the way out, and --extract-media=./media to pull images out on the way back in.
Almost everyone who writes in markdown eventually hits the same wall: someone needs a .docx. Legal wants track changes. Your editor works in Word. The grant application demands a Word template. And the reverse happens just as often — you're handed a 40-page Word document and you'd rather work on it as plain text.
Both directions are solved problems. Neither is lossless. Here's exactly what works, what breaks, and how to control it.
Install Pandoc
Pandoc is the workhorse for every conversion in this article. On macOS:
brew install pandoc
That's the entire setup for DOCX. You only need a LaTeX engine if you're also generating PDFs — see exporting markdown to PDF, HTML, and Word for that side of it.
Markdown to Word
The basic command:
pandoc input.md -o output.docx
Pandoc infers the output format from the .docx extension. The result is a real Word document — not HTML renamed, not RTF. It opens in Word, Pages, LibreOffice, and Google Docs.
A few flags worth knowing:
# Add a table of contents
pandoc input.md --toc -o output.docx
# Treat the input as GitHub Flavored Markdown (task lists, strikethrough, tables)
pandoc -f gfm input.md -o output.docx
# Split into numbered sections
pandoc input.md --number-sections -o output.docx
If your markdown has YAML frontmatter, Pandoc reads title, author, and date from it and uses them for the document's title block and file metadata. Everything else in the frontmatter is ignored rather than dumped into the body — which is usually what you want.
Styling the Word Output with a Reference Doc
By default, Pandoc's Word output uses its own built-in styles. They're clean but generic. If you need company fonts, specific heading sizes, or a house template, use a reference doc.
Start by exporting Pandoc's default template so you have something valid to edit:
pandoc -o custom-reference.docx --print-default-data-file reference.docx
Open custom-reference.docx in Word. Do not write content in it — instead, edit the styles: Heading 1, Heading 2, Body Text, Source Code, Block Text, Table, and so on. Change fonts, sizes, colors, spacing. Save it.
Then use it for every conversion:
pandoc input.md --reference-doc=custom-reference.docx -o output.docx
Every heading, paragraph, and code block in the output now picks up your styles. This is the correct way to hand a designer control over Word output while you keep writing plain text. Keep the reference doc in version control next to your markdown.
A caveat: Pandoc maps content to a fixed set of style names. If your corporate template calls its heading style "CompanyHead" instead of "Heading 1", Pandoc won't find it. Rename the styles in the reference doc to match Pandoc's expected names rather than the other way around.
What Survives and What Breaks
I converted a document to DOCX and back to check. Here's the honest accounting:
| Markdown feature | Markdown → DOCX | DOCX → Markdown |
|---|---|---|
| Headings, bold, italic, links | Clean | Clean |
| Bulleted and numbered lists | Clean | Clean (nesting sometimes flattens) |
| Tables | Survive as real Word tables | Survive as pipe tables |
| Footnotes | Become Word footnotes | Come back as markdown footnotes |
| Inline and display math | Converted to OMML (Word equations) | Converted back to LaTeX |
| Fenced code blocks | Styled text, language tag lost | Return as indented code, no language |
| Mermaid diagrams | Plain text in a code block | Plain text — the diagram is gone |
| Images | Embedded in the docx | Need --extract-media |
| Task list checkboxes | Rendered as characters, not checkboxes | Return as literal characters |
Two of those deserve detail.
Math actually works. Pandoc converts LaTeX math to OMML — Office Math Markup Language — which is Word's native equation format. $E = mc^2$ becomes an editable Word equation, not an image. Converting back turns it into LaTeX again, though the delimiters may change (I got \(E = mc^2\) rather than $E = mc^2$ on the round trip). If you rely on $...$, run a find-and-replace after converting, or pass -t markdown+tex_math_dollars.
Mermaid does not work. Pandoc has no idea what Mermaid is — to it, a ```mermaid block is just a code block containing text. Word gets the source code, not a diagram. If you need the diagram in the Word file, render it to SVG or PNG first (the Mermaid CLI does this) and reference the image in your markdown before converting.
The same applies to any renderer-specific extension. Word only receives what Pandoc's document model can represent.
Word to Markdown
Going the other direction:
pandoc input.docx -o output.md
For most purposes you want more control than the default:
pandoc input.docx -t gfm --wrap=none --extract-media=./media -o output.md
-t gfmproduces GitHub Flavored Markdown — pipe tables, strikethrough, task lists — instead of Pandoc's own extended dialect.--wrap=nonestops Pandoc from hard-wrapping paragraphs at 72 characters. Hard wraps look fine in a terminal and terrible in a diff.--extract-media=./mediapulls every embedded image out of the docx into amedia/folder and rewrites the image links to point at them. Without it, images embedded in the Word file are simply dropped.
Expect to clean up afterward. Word documents accumulate junk: empty paragraphs used as spacing, manual line breaks mid-sentence, character-level formatting applied to single words, text boxes that don't map to anything. Pandoc converts faithfully, which means it converts the junk too.
Track Changes
If the docx has tracked revisions, Pandoc lets you choose what to do with them:
# Accept all tracked changes (this is the default)
pandoc input.docx --track-changes=accept -o output.md
# Reject them — convert the original text
pandoc input.docx --track-changes=reject -o output.md
# Keep both, marked up with spans
pandoc input.docx --track-changes=all -o output.md
--track-changes=all is the useful one when you actually care about the edit history: insertions and deletions come through as marked spans so you can see who changed what. It produces messy markdown, so treat it as a review artifact rather than your new source file.
Comments in the docx are dropped unless you use all. If the comments matter, read them in Word before converting.
Online Converters and the Privacy Tradeoff
There are plenty of browser-based markdown-to-Word and docx-to-markdown converters, and they're genuinely convenient for a one-off file. The tradeoff is simple and worth stating plainly: you are uploading the document to someone else's server.
For a blog draft, that's fine. For a contract, a performance review, unreleased financials, or anything covered by an NDA, it isn't. Pandoc runs entirely on your machine and never touches the network. Given that installing it takes one Homebrew command, the local route is usually the right default for anything you wouldn't email to a stranger.
If you must use a web converter, check whether it processes files in the browser or uploads them, and check the retention policy.
Word's Own Markdown-ish Behavior
Word doesn't import markdown files, but it does have AutoFormat As You Type, which recognizes some markdown-like patterns while you type: *text* becomes bold, _text_ becomes italic, a hyphen followed by a space starts a bulleted list, 1. starts a numbered list, and three hyphens on their own line become a horizontal border.
This is helpful if you type in markdown habits, and infuriating if you're trying to paste actual markdown source into Word — you'll get half-converted text with stray asterisks everywhere. The settings live in Word's AutoCorrect Options under "AutoFormat As You Type," and you can turn them off individually.
Pasting raw markdown into Word does not convert it. Headings stay as ##. Use Pandoc.
Google Docs handles this differently and rather better — see how to convert markdown to Google Docs for the native import and export path there.
A Practical Round-Trip Workflow
When you own the source and Word is only a delivery format:
- Keep the
.mdfile as the single source of truth, in git. - Maintain one
reference.docxalongside it for styling. - Export with
pandoc draft.md --reference-doc=reference.docx -o draft.docxwhenever someone needs a Word copy. - Treat the
.docxas a build artifact. Never edit it and expect the change to come back.
When someone else owns the source and hands you Word files, convert once with --extract-media, clean up the result, and from then on work in markdown. Round-tripping a document repeatedly between the two formats compounds the losses — each pass drops a little more structure.
Once the markdown exists, read it somewhere that renders it properly. OpenMark opens a converted file and shows the formatted result immediately, so you can spot the places where a Word table came through mangled or a heading level got flattened before you commit the file.
Download OpenMark → — $9.99, one-time, native macOS. Read and edit the markdown that comes out of your conversions, with live rendering for tables, math, and code blocks.