Markdown to Word with Pandoc

Pandoc Markdown to Word: what it does, what it drops, and how to fill the gaps

Pandoc is the reference tool for document conversion and its .docx writer is excellent. It produces real Heading styles, native tables, list numbering and, remarkably, native Word equations from LaTeX without needing a LaTeX installation, because it writes OMML directly. If you live in a terminal and convert the same kind of file every week, a Makefile with a pandoc line is hard to beat. This page explains the command, the flags that make a difference, and the specific places where the output falls short so you can decide what to do about them.

The commands

The minimal form is pandoc in.md -o out.docx. Pandoc infers the output format from the extension. Its default input dialect is Pandoc's own Markdown, which differs from GitHub's: pipe tables work, but task lists, strikethrough with tildes and autolinked URLs need -f gfm. To match the look of an existing document, run pandoc --print-default-data-file reference.docx > styles.docx, open styles.docx in Word, modify the styles Normal, Heading 1 to 6, Body Text, Source Code, Block Text, Table and Compact, save, and pass --reference-doc=styles.docx. --toc inserts a table of contents field that Word fills in when you open the file and accept the update prompt. --number-sections prefixes headings with numbers, and --resource-path tells Pandoc where to find relative images. For math, nothing extra is required; $…$ and $$…$$ convert to equations by default.

Where the output loses fidelity

Mermaid. A ```mermaid block is just a code block to Pandoc and arrives in Word as monospace text. Rendering it requires the mermaid-filter package, which pulls in Node.js and a headless Chromium, and the output is a fixed-DPI PNG. Image size. Pandoc embeds images at their pixel dimensions using 96 dpi. A 1600-pixel screenshot becomes a 42 cm picture that overflows the page until you resize it by hand or add {width=100%} attributes to every image in the source. Heading and table styles. Without a reference document the output uses Pandoc's plain defaults, and table header shading is absent because Pandoc's default table style has none. Equation numbering. Pandoc does not number display equations; that requires the pandoc-crossref filter, a separate Haskell binary that must match your Pandoc version. Column widths. Pipe tables get equal widths unless the dash counts in the separator row are made proportional to the desired widths, which nobody remembers to do. Preview. There is none; you open the .docx to find out.

How MDtoDOCX covers the gaps

MDtoDOCX uses the same style names as Pandoc, so a reference document built for Pandoc works as a Word template here with no changes. On top of that it renders Mermaid diagrams to SVG in the browser, scales images to the printable width automatically, estimates table column widths from content and shades header rows, numbers display equations with SEQ fields and resolves cross-references without a filter, and shows a live Word-style preview before you download. Nothing is installed and nothing is uploaded. The trade-off is that Pandoc scripts and runs in batch on a server, while MDtoDOCX runs interactively in a tab; Pro adds batch conversion for people who need both.

Using the two together

They are not exclusive. A common pattern is to keep Pandoc in a CI pipeline for release notes and use MDtoDOCX for anything with diagrams, screenshots or equations that needs to look right the first time. Because both produce standards-compliant .docx files, a document from either can be post-processed by the other or opened in Word, LibreOffice and Google Docs. For inline math specifics see Markdown to Word with formulas, and for the inline formatting mapping that both tools share, see Markdown to Word with formatting.

Frequently asked questions