Pandoc MD to DOCX
How to convert Markdown to Word with pandoc, the options that matter for .docx, and a builder that writes the command for you.
pandoc -f gfm README.md -o README.docx
The basic command
pandoc input.md -o output.docxWhen you don’t name the formats, pandoc guesses them from the file extensions, so this reads input.md as Markdown and writes a Word document. To be explicit, use -f (from) and -t (to): pandoc -f markdown -t docx input.md -o output.docx.
Options worth knowing for Word output
| Option | What it does |
|---|---|
-f gfm | Read the input as GitHub-Flavored Markdown instead of pandoc’s own Markdown. |
-s --toc | Insert a table of contents. --toc needs -s (standalone). |
--toc-depth=2 | How many heading levels the contents list includes (default 3). |
-N, --number-sections | Number the headings. |
--reference-doc=FILE | Take styles, margins and page size from a .docx you prepared. |
--resource-path=.:images | Where to look for images referenced in the Markdown (separate folders with : on macOS and Linux, ; on Windows). |
Custom styles with a reference document
Pandoc styles its Word output from a reference .docx. To make your own:
pandoc -o custom-reference.docx --print-default-data-file reference.docxOpen custom-reference.docx in Word or LibreOffice, change the styles (Normal, Heading 1, Title and so on), and save it. The manual advises changing only the styles, not the content. Then convert with it:
pandoc input.md --reference-doc=custom-reference.docx -o output.docxWord to Markdown with pandoc
pandoc -f docx -t gfm input.docx -o output.md --extract-media=media--extract-media writes the document’s images into the media folder and points the Markdown at them. Pandoc accepts tracked changes by default (--track-changes=accept); use reject or all to change that. Prefer not to install anything? The DOCX to Markdown converter does this in your browser.
Pandoc or the browser converter?
| Pandoc | This site’s converter | |
|---|---|---|
| Installation | Install pandoc on your computer | Nothing to install; works in a browser |
| Batch and scripted conversion | Yes | One document at a time |
| Styling | Any style, through a reference .docx | Font, size and page size |
| Citations, templates, filters | Yes | No |
| Live preview before converting | No | Yes |
| Where the conversion happens | On your computer | In your browser, on your device |
For a quick conversion without the command line, use the MD to DOCX converter. Installation instructions for pandoc are on the official pandoc installing page, and every option is documented in the pandoc User’s Guide.
Frequently asked questions
What is the pandoc command to convert Markdown to Word?
pandoc input.md -o output.docx. Pandoc works out the input and output formats from the file extensions, so .md is read as Markdown and .docx is written as a Word document.
How do I change the fonts and styles pandoc uses?
Create a reference document with pandoc -o custom-reference.docx --print-default-data-file reference.docx, open it in Word or LibreOffice, modify the styles, save it, and then convert with --reference-doc=custom-reference.docx.
How do I add a table of contents?
Add -s --toc. The pandoc manual notes that --toc has no effect unless -s (--standalone) is used. Use --toc-depth to control how many heading levels are listed; the default is 3.
Should I use -f gfm?
If your Markdown was written for GitHub (a README, for example), -f gfm reads it as GitHub-Flavored Markdown. Without it, pandoc reads its own extended Markdown dialect.
Do I need pandoc at all?
Not for one-off conversions: the MD to DOCX converter on this site runs in your browser with nothing to install. Pandoc is the better choice for scripts, batch jobs, citations and templates.
Can pandoc convert DOCX back to Markdown?
Yes, for example pandoc -f docx -t gfm input.docx -o output.md. Add --extract-media=DIR to save the document's images into a folder.