---
title: "Converting Word to Markdown With Pandoc"
description: "The Pandoc command that turns a .docx into clean Markdown, the flags that matter, what it gets wrong, and when a browser converter is the easier choice."
url: "https://md-to-word.com/guides/pandoc-word-to-markdown/"
---

# Converting Word to Markdown With Pandoc

By [Hassan Razeen](https://md-to-word.com/about/) · 6 September 2026

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](https://md-to-word.com/word-to-markdown/) 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`](https://pandoc.org/MANUAL.html).** 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](https://md-to-word.com/word-to-markdown/) 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](https://md-to-word.com/guides/pandoc-vs-online-converters/) 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, Pandoc is free. It is open source, released under the GPL, and used widely in academic publishing.

**Does Pandoc need Microsoft Word installed?** No, Pandoc does not need Microsoft Word installed. 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 converts in both directions. `pandoc report.md -o report.docx` converts Markdown to Word, and the same site’s [Markdown to Word converter](https://md-to-word.com/) does it in the browser, with a best quality mode that runs Pandoc itself.

## Related guides

-   [Pandoc or an online converter: which should you use?](https://md-to-word.com/guides/pandoc-vs-online-converters/)
-   [How to keep Markdown tables intact](https://md-to-word.com/guides/markdown-tables-to-word/)
-   [Why your formatting disappears converting Markdown to Word](https://md-to-word.com/guides/keep-formatting-markdown-word/)

Need to do this now? The [Markdown to Word converter](https://md-to-word.com/) runs in your browser and never uploads your file. Going the other way, use the [Word to Markdown converter](https://md-to-word.com/word-to-markdown/).