Converting Word Documents to Markdown (and Back)

Word and Markdown serve different purposes. As we covered in Markdown vs Rich Text, Markdown excels at portability, version control, and focused writing, while Word is the standard for business documents, collaboration, and print layouts.

Common scenarios where you need to convert:

• Legacy docs to modern workflows — Migrating old Word docs into a Git-based documentation system.
• Draft in Markdown, deliver in Word — Writing in a distraction-free editor, then formatting for a client or manager.
• Collaborative round-trips — Someone edits in Word, you want to pull changes back into Markdown.
• Content migration — Moving blog posts or knowledge base articles between platforms.

Pandoc (CLI — The Swiss Army Knife)

Pandoc is the gold standard for document conversion. It handles dozens of formats and produces clean Markdown output.

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

# With options for cleaner output:
pandoc input.docx -t markdown --wrap=none --extract-media=./media -o output.md

The --extract-media flag pulls embedded images into a folder. The --wrap=none flag prevents Pandoc from inserting hard line breaks at 72 characters.

Mammoth (JavaScript Library)

Mammoth converts .docx to HTML, which you can then convert to Markdown. It's particularly good at producing semantic HTML — it maps Word styles to HTML elements rather than preserving visual formatting.

Online Converters

Web-based tools like MarkdownFTW let you drag and drop a Word file and get clean Markdown instantly — no install required. Everything runs in your browser, so your document never leaves your device.

Copy-Paste from Word

The simplest approach: copy content from Word and paste it into a Markdown editor that supports rich text paste. Many editors will auto-convert the formatting. Results vary — simple documents convert well, complex layouts don't.

Converting Markdown to Word is generally easier because you're going from a simpler format to a richer one.

Pandoc

pandoc input.md -o output.docx

# With a custom template for branding:
pandoc input.md --reference-doc=template.docx -o output.docx

The --reference-doc flag lets you apply a Word template with your fonts, colors, and styles. Write once in Markdown, output branded documents every time.

Browser-Based Export

Tools like MarkdownFTW generate Word documents directly in your browser using JavaScript libraries. No server required — paste or write your Markdown, click export, get a .docx file. You can also export to PDF, PowerPoint, Excel, and HTML from the same source.

The general rule: structural content converts well, visual formatting doesn't. If your document relies on how it looks rather than how it's structured, expect some manual cleanup after conversion.

1. Use Word styles properly. Documents that use built-in heading styles (Heading 1, Heading 2) instead of manually formatting text convert much better than documents where someone just made text big and bold.
2. Clean up before converting. Remove tracked changes, accept all edits, and delete empty paragraphs. Conversion tools handle clean documents better.
3. Handle images separately. Extract images before conversion (Pandoc's --extract-media does this). Check that image paths in the output Markdown are correct.
4. Review the output. No conversion is perfect. Skim the result, fix any formatting artifacts, and verify links still work.
5. Use templates for recurring exports. If you regularly convert Markdown to Word, create a reference template with your branding and styles.

The most practical workflow for teams that span both formats:

1. Write and maintain your content in Markdown (version controlled, portable).
2. Export to Word when you need to share with non-technical colleagues.
3. If they make edits in Word, convert back to Markdown and diff the changes.
4. Merge their edits into your Markdown source of truth.

This keeps Markdown as your single source of truth while accommodating people who prefer Word. It's not seamless — round-tripping always loses some formatting — but it's practical and it works.