How to Convert Word and Google Docs to Markdown with Pandoc

A Word document or Google Doc doesn't turn into Markdown on its own. You need one tool in between: Pandoc. Once your file is in the right starting format, the whole conversion is a single command.

Quick answer

Export your Google Doc as a Word file first — Google Docs has no native Markdown export — then run:

pandoc -f docx -t markdown input.docx -o output.md

Starting from an actual .docx file? Skip the export step; the same command works. The rest of this covers exporting from Google Docs, choosing the right Markdown flavor, keeping your images, and the handful of things that commonly go wrong.

Step-by-step

Export the Google Doc to .docx

In Google Docs, go to File > Download > Microsoft Word (.docx) and save it in the folder where you'll run the conversion. Google Docs can't hand Pandoc a native format directly, so .docx is the standard bridge format.

Run the core Pandoc command

pandoc -f docx -t markdown input.docx -o output.md

-f (--from) tells Pandoc what format you're converting from; -t (--to) sets the target. Pandoc's manual is upfront that this is a lossy conversion in places. It preserves structural elements like headings, lists, and links. Fine formatting details like margins don't make it, and complex tables may not survive intact either.

Pick the right output flavor

Pandoc doesn't produce just one kind of Markdown:

• -t markdown — Pandoc's own extended dialect: tables, footnotes, YAML metadata blocks
• -t gfm — matches GitHub Flavored Markdown, which is a strict superset of CommonMark with tables, strikethrough, task lists, and autolinks
• -t commonmark — the strict base spec, the safest choice if the Markdown needs to render correctly in the widest range of tools

Headed anywhere that renders GFM — a README, a wiki, a GFM-based editor? Use -t gfm. Need maximum portability instead? Use -t commonmark. Reference-style links versus inline links is one place conversion output can look different across tools; see our notes on inline vs reference-style links for how to tell them apart.

Extract the embedded images

Add --extract-media:

pandoc -f docx -t gfm --extract-media=./media input.docx -o output.md

Pandoc pulls every embedded image into a media folder and rewrites the Markdown to reference each file by relative path. Nothing gets left behind in the original .docx.

Keep metadata and add a table of contents

Add -s (--standalone) to get a YAML front-matter block with title, author, and date pulled from the document properties. Add --toc to generate a table of contents from the document's headings — worth doing on anything long enough to need headings that stay navigable.

Common problems and fixes

Tracked changes turn into clutter

If the source document has tracked changes, Pandoc defaults to accepting them silently. To control this explicitly:

pandoc --track-changes accept input.docx -o output.md

Use reject to discard proposed edits, or all to keep insertions and deletions as styled spans in the output — useful if you still need to review them.

Tables come out wrong

Complex tables — merged cells, nested formatting — don't always survive the trip. That's not a bug to fix; it's a known limit of Pandoc's document model, which is simpler than Word's. Simplify the table in the source document first if the structure matters more than the conversion speed.

Odd characters show up in the output

Pandoc expects UTF-8 in and out. If your source file uses a different encoding, pipe it through iconv before handing it to Pandoc.

Headings lose their structure

If the converted Markdown flattens your outline or skips heading levels, check the source document's heading styles (Heading 1, Heading 2, and so on) rather than manually bolded text. Pandoc maps styles to Markdown heading levels, not visual formatting.

Doing this with Carets

Once the conversion is done, you're left with a plain-text .md file — and that's exactly what Carets is built to work with. Carets is a fast, native notes and code editor for iPhone, iPad, and Mac that handles Markdown, plain text, and code with real syntax highlighting, no reformatting round-trip required.

Two things make it a good fit here. Your converted files stay organized into files, projects, and tags instead of getting lost in a folder of loose .md exports. And because Carets is native and fast rather than a web wrapper, opening a freshly converted document to check the output is instant. If Pandoc conversion is becoming part of how you write, a plain-text note-taking system built around files you actually own is worth setting up alongside it.

Carets is available on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

Can Pandoc convert a Google Doc to Markdown directly?

Not directly. Google Docs has no native Markdown export, so the reliable path is File > Download > Microsoft Word (.docx), then run Pandoc on that exported file.

What's the difference between -t markdown, -t gfm, and -t commonmark in pandoc?

All three are Markdown outputs, but they differ in extensions. -t markdown is Pandoc's extended dialect (tables, footnotes, YAML metadata). -t gfm matches GitHub's rendering (tables, strikethrough, task lists, autolinks) and is the safer default for docs meant to render on GitHub or in a GFM-based app. -t commonmark sticks to the strict base spec for maximum portability.

Will I lose formatting when converting a Word doc to Markdown?

Some, yes. Pandoc preserves structural elements — headings, lists, links, basic emphasis — but not fine formatting details like margins, and complex tables may not survive intact. Expect a clean structural conversion, not a pixel-perfect one.

How do I keep the images from my Word or Google Doc after converting?

Add --extract-media=./media to the Pandoc command. It pulls every embedded image into a media folder and rewrites the Markdown to reference them by relative path.