Converting Word to Markdown With Pandoc

The command is one line:

pandoc report.docx -t gfm --wrap=none --extract-media=media -o report.md

That reads a Word document, writes GitHub Flavored Markdown without hard line wraps, and saves any images into a media folder next to the output. For most documents it is all you need. The rest of this guide explains each part of that command, the cases where Pandoc’s output needs cleaning up, and when the Word to Markdown converter on this site is the easier tool for the job.

Installing Pandoc

Pandoc is a free, open source command line program. Installers for Windows and macOS are on pandoc.org, and every Linux distribution packages it. On macOS with Homebrew it is brew install pandoc. Check it works with pandoc --version.

The command, part by part

The input file. Pandoc works out the input format from the .docx extension. It reads only the modern Word format; a legacy .doc has to be saved as .docx in Word first.

-t gfm. Write GitHub Flavored Markdown. Pandoc’s default Markdown flavour adds attributes, fenced divs and other extensions that GitHub, most editors and most static site generators do not understand. If the output is going into a repository, a wiki or a note-taking app, gfm is the flavour you want.

--wrap=none. By default Pandoc wraps paragraphs at 72 columns, which puts a line break in the middle of every long sentence. That is harmless for rendering but painful for editing and for diffs. none keeps each paragraph on one line.

--extract-media=media. Images inside a .docx are files inside the zip. This flag writes them out to a folder and links to them from the Markdown. Without it, the images are referenced but do not exist on disk.

-o report.md. The output file. Leave it out and Pandoc prints to the terminal.

Flags worth knowing

Tracked changes. By default Pandoc accepts all tracked changes and drops comments. --track-changes=reject produces the document as it was before the changes, and --track-changes=all keeps insertions and deletions as annotated spans so nothing is lost. Choose before converting, because the Markdown has no memory of the alternative.

Custom styles. Adding +styles to the input format, as -f docx+styles, keeps every custom paragraph style as a labelled div. That is useful for documents with meaningful house styles and noise for everything else.

Heading style. Pandoc writes # headings by default in current versions. Older versions wrote underlined headings; --markdown-headings=atx forces the hash form if you are on one.

Reference links. --reference-links moves link targets to the end of the document, which some people find more readable in source form.

What Pandoc gets wrong, and why

Pandoc reads the document’s structure, which is the right thing to do and also the reason its output can surprise people.

Manual formatting is not structure. A heading that was made by selecting text and pressing bold is a bold paragraph, not a heading, and Pandoc writes it as bold text. The fix is in Word: apply real heading styles before converting. The same applies to lists made with typed numbers and to tables drawn with tabs.

Merged cells. Markdown tables cannot express a cell that spans rows or columns. Pandoc flattens the table as best it can, and the result usually needs a look.

Text boxes and shapes. Content inside floating text boxes is often out of reading order or missing. Move it into the main flow first.

Footnotes. Pandoc handles these well; they become Markdown footnotes. This is one of its advantages over most other tools.

Images. They are extracted faithfully but named by position, not by anything meaningful. Rename them if the Markdown will be maintained.

Converting many documents

The command line earns its place when there are many files. A shell loop converts a whole folder:

for f in *.docx; do pandoc "$f" -t gfm --wrap=none -o "${f%.docx}.md"; done

On Windows, the same idea works in PowerShell with a foreach over Get-ChildItem. This is the case where a browser converter, which takes one file at a time, is the wrong tool.

When the browser converter is easier

The Word to Markdown converter on this site does the same job for one document without installing anything. It reads the .docx in your browser, maps heading styles to Markdown headings in the same structural way Pandoc does, writes GFM tables, keeps code blocks, and lists any styles it could not represent. Nothing is uploaded.

Use it when you have one document and want the Markdown in the next thirty seconds, when you are on a machine where you cannot install software, or when the person doing the conversion would rather not open a terminal. Use Pandoc when you have many files, need tracked changes preserved, or want the extracted images on disk automatically. The Pandoc comparison guide looks at the same trade-off in the other direction, from Markdown to Word.

Checking the result

Pandoc’s output is correct far more often than it is pretty, so read the Markdown once before committing it.

The most common surprise is escaping. Pandoc puts a backslash before characters that could be mistaken for Markdown syntax, so a file name like report_final_v2 comes out as report\_final\_v2 in prose. The escapes render correctly, but they are noise in the source. A search and replace after the fact, or wrapping such names in backticks in the original document, avoids it.

Smart quotes and non-breaking spaces come through as the characters they are, which most editors show as ordinary quotes and spaces. They only matter if the Markdown will be processed by something strict about plain ASCII.

Finally, compare the headings in the Markdown against Word’s navigation pane. If a heading is missing from the Markdown, it was manual formatting in Word, and that is a fix in the source document rather than in Pandoc.

Common problems

Every line is wrapped at 72 characters. Add --wrap=none.

Headings came out as bold text. They were manual formatting in Word. Apply heading styles and convert again.

Images are referenced but not present. Add --extract-media=media, or a folder name of your choice.

The output has strange braces and colons. You wrote Pandoc’s own Markdown flavour. Add -t gfm.

A table looks broken. It probably had merged cells. Simplify the table in Word first, or fix the Markdown by hand.

Comments disappeared. Pandoc drops comments unless you keep tracked changes with --track-changes=all.

Frequently asked questions

Is Pandoc free? Yes. It is open source, released under the GPL, and used widely in academic publishing.

Does Pandoc need Microsoft Word installed? No. It reads the .docx file directly.

Which Markdown flavour should I write? GFM, with -t gfm, unless you have a specific reason to want Pandoc’s extensions. It is what GitHub, GitLab, Obsidian and most static site generators read.

Can I go the other way with the same tool? Yes. pandoc report.md -o report.docx converts Markdown to Word, and the same site’s Markdown to Word converter does it in the browser, with a best quality mode that runs Pandoc itself.