Markdown to DOCX with Pandoc

The smallest command is pandoc in.md -o out.docx. Pandoc reads the Markdown, builds an internal document, and writes a DOCX package. Headings become Word headings, lists become Word lists, and fenced code blocks become styled paragraphs.

The output is editable because DOCX is a document model, not a fixed page. That also means the file may paginate differently on another machine if fonts, margins, or Word versions differ.

A reference DOCX tells Pandoc which Word styles to use. Create a Word file with the styles you want, then run pandoc in.md -o out.docx --reference-doc=reference.docx. The reference does not act like a template with body placeholders; it supplies style definitions and document settings.

This is the right way to control fonts, heading appearance, code block styling, margins, and other Word defaults. Editing the generated file afterward works, but it is not repeatable across many documents.

Headings, paragraphs, emphasis, links, simple lists, fenced code blocks, block quotes, footnotes, and basic pipe tables usually map well. Images work when paths are correct and the image format is supported by Word.

Task lists, complex nested HTML, custom containers, and diagram syntaxes need care. Pandoc can sometimes preserve raw content for formats that support it, but DOCX is not HTML. If the source is really a web page, convert from HTML with explicit expectations.

DOCX tables have rows and cells, but Markdown tables do not express every Word table feature. Column widths, merged cells, captions, and long code inside cells can shift. For formal tables, consider authoring in DOCX or using a Pandoc filter.

Images should be stored locally and referenced with relative paths. If a Markdown export points to web URLs or an app-private attachments folder, download the images before conversion. Otherwise the DOCX may contain missing image placeholders.

After conversion, check heading levels in Word’s navigation pane, list numbering, table borders, code blocks, links, alt text, and footnotes. If the document will be reviewed with track changes, also check that paragraphs are real paragraphs rather than many separate runs.

For a PDF final, you can generate DOCX for editing and then export DOCX to PDF. Do not expect a Markdown-to-DOCX-to-PDF path to match direct Markdown-to-PDF output exactly; the layout engines differ.

Reference documents should be treated as source files. Store the reference DOCX beside the project, name its purpose, and update it through review. If every writer uses a different local reference file, generated DOCX files will not have stable styles.

Before sending the DOCX, open it in Word or LibreOffice and use the navigation pane. Missing headings, broken list nesting, and unstyled code blocks are easier to fix in Markdown or the reference document than after reviewers add comments.

If reviewers require comments and tracked changes, generate DOCX early rather than after the Markdown is finished. Word review can introduce edits that are hard to merge back into Markdown, so define which file is authoritative during review.

For long documents, check the table of contents after conversion. It reveals heading-level mistakes that are easy to miss while scrolling.

A final Markdown-to-Word process should define how edits return to the source. If Word comments are accepted directly in DOCX, assign someone to port those changes back to Markdown before the next generation.

For generated reports, include the exact command in the repository documentation so another maintainer can reproduce the same DOCX.