DOCX to Markdown: Free Tool & Python Guide

DOCX to Markdown: Convert Word Docs Without Breaking Everything

Written by Priya Shah, Technical Documentation Lead specializing in OOXML and docs-as-code migrations. Last updated September 2026.

Last month I copied a 20-page spec out of Word and pasted it straight into our docs site. What landed in the editor wasn't a document — it was a wall of <span style="mso-bidi-font-weight:normal"> tags, three different font-size resets per paragraph, and a table that had somehow gained an extra invisible column. Twenty minutes of find-and-replace later, I still hadn't gotten the bullet points to stop nesting inside each other.

If you've tried to move a Word file into GitHub, Obsidian, Notion, or a static site generator like Hugo or Astro, you've probably hit some version of this. The fix isn't "paste more carefully." It's converting docx to markdown properly in the first place, so the structure survives and the formatting noise doesn't.

Quick answer: if you just need a file converted right now, drop it into md-convert's DOCX to Markdown tool. It runs entirely in your browser, keeps headings, lists, tables and images intact, and doesn't touch a server. Keep reading if you want to understand why Word conversions break in the first place — it'll save you time on the next document too.

Why Markdown Is the Format Everyone Actually Wants

Word was built for print. It cares about exact fonts, exact spacing, and page layout that looks identical whether you're on a Mac or a decade-old PC. None of that matters once your content lives in a repo, a wiki, or a prompt window.

Markdown strips all of that away and keeps only structure and meaning:

• Git-friendly diffs. A one-line edit in a .md file shows up as a one-line diff. The same edit in a .docx shows up as a wall of binary noise in a pull request.
• Tool-agnostic. Obsidian, Notion, VS Code, GitHub, and just about every static site generator treat .md as a native format. Nothing needs a plugin to open it.
• Cheaper for AI pipelines. If you're feeding docs into an LLM or a RAG pipeline, Markdown carries the same information in a fraction of the tokens a Word export would use, and headings stay usable as chunk boundaries instead of collapsing into flat text.
• Readable as plain text. You can open a .md file in Notepad and still understand it. Try that with the XML inside a .docx.

Factor	Word (.docx)	Markdown (.md)
Diffing in Git	Unreadable binary changes	Clean, line-by-line diffs
Opening the file	Needs Word or a compatible app	Any text editor
AI / RAG ingestion	Noisy, layout-heavy extraction	Clean, chunkable, low token count
Editing on the go	Awkward on mobile, needs the app	Any plain-text editor works
Portability	Tied to the Office ecosystem	Works everywhere, forever

None of this means Word is a bad tool — it's genuinely good at what it's for. It just isn't what a documentation pipeline, a knowledge base, or a model's context window wants to read.

What a .docx File Actually Is (and Why That Matters)

Here's the part most people never think about: a .docx file isn't really a "document." It's a ZIP archive. Rename one to .zip, extract it, and you'll find a small filesystem inside — word/document.xml for the body text, word/styles.xml for named styles, word/numbering.xml for list formats, and a media/ folder for any images.

This matters because it explains exactly why some Word documents convert beautifully and others turn into a mess of bold paragraphs with no heading structure at all.

Every paragraph in that XML can carry a pStyle reference — a pointer to a named style like "Heading 2." When a paragraph has that reference, the conversion is exact: the style name states the level, so mapping it to ## isn't a guess. Here's what that looks like in practice.

A properly styled heading, in the source XML:

xml

<w:p>
  <w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
  <w:r><w:t>Migration Checklist</w:t></w:r>
</w:p>
<w:p>
  <w:r><w:t xml:space="preserve">Complete before </w:t></w:r>
  <w:r><w:rPr><w:b/></w:rPr><w:t>Friday</w:t></w:r>
  <w:r><w:t>, or the sprint slips.</w:t></w:r>
</w:p>
<w:p>
  <w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="3"/></w:numPr></w:pPr>
  <w:r><w:t>Export the legacy wiki pages</w:t></w:r>
</w:p>

What that becomes in Markdown:

markdown

## Migration Checklist

Complete before **Friday**, or the sprint slips.

- Export the legacy wiki pages

Clean mapping, no ambiguity. Now compare it to a document where someone typed the same heading but never applied a heading style — just bolded the text and bumped the font size by hand:

xml

<w:p>
  <w:pPr><w:rPr><w:b/><w:sz w:val="32"/></w:rPr></w:pPr>
  <w:r>
    <w:rPr><w:b/><w:sz w:val="32"/></w:rPr>
    <w:t>Migration Checklist</w:t>
  </w:r>
</w:p>

There's no pStyle here, no semantic signal that this line means anything different from a normal paragraph. A converter has no reliable way to know it should be a heading, so it comes out as:

markdown

**Migration Checklist**

Bold text, same visual size in Word, but structurally just a paragraph. This is the single most common reason people ask "why did my headings disappear" after a conversion — the document never had real headings to begin with, just text that looked like headings. If you control the source file, applying real heading styles from Word's Styles gallery before exporting fixes this completely, and it's worth the two minutes.

Fonts, colors, character spacing, page numbers, headers and footers, and section breaks all get dropped in conversion too — not because a converter is lazy about them, but because Markdown has no page model and no concept of visual styling. That loss is a property of the format, not a bug.

How to Convert DOCX to Markdown (3 Ways)

There are really three routes here, and which one makes sense depends on how many files you're converting and how much control you want over the output.

Method 1: The Manual Way (Don't)

You can, technically, open a .docx, copy the text into a plain editor, and manually type # before every heading and - before every list item. For a two-paragraph memo, sure. For anything longer, this is how you lose an afternoon — and you'll still miss table formatting, nested lists, and links, because none of that survives a plain copy-paste without extra cleanup. Skip this unless the file is genuinely tiny.

Method 2: The CLI Route — Pandoc

Pandoc is the standard command-line tool for this and it's genuinely good. Once it's installed, converting a modern .docx is one line:

bash

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

The -t gfm flag targets GitHub Flavored Markdown, which is what most tools (GitHub, GitLab, most static site generators) expect. If your document has embedded images, add the media-extraction flag so they land in a real folder instead of getting dropped:

bash

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

Pandoc handles headings, lists, tables, links, and footnotes well, and it runs entirely on your machine. The friction is setup: you need it installed, you need a terminal, and if you're on a locked-down work laptop where you can't install software, this route is closed to you.

Method 3: The Instant Web Route

For a one-off conversion, or if you just don't want to touch a terminal, md-convert's DOCX to Markdown tool does the same job in a browser tab. Drop the file in, and it reads the .docx locally using Mammoth.js, maps the named styles to semantic HTML, and converts that to clean Markdown — headings, nested lists, tables, links, and images all come through intact.

The difference from a typical online docx to markdown converter is that nothing gets uploaded anywhere. The file is read with the browser's own File APIs and processed in a background Web Worker, so contracts, HR documents, or anything else you'd rather not send to a third-party server never leave your device. You can confirm that yourself: open your browser's DevTools Network panel while converting and watch — no request carries your file.

Convert Word to Markdown with Images (and Tables That Don't Fall Apart)

Images and tables are where most word to markdown converter tools quietly disappoint people, so it's worth knowing what's actually happening under the hood.

Images in a .docx live in the media/ folder inside the ZIP, referenced by relationship IDs from the body text. When you convert, there are two honest options: embed each image as a base64 data URI directly inside the Markdown, or extract them as real image files and reference them with relative paths.

• Base64 inline keeps everything in one self-contained .md file — nothing to lose track of, but the file gets large fast, and most static site generators would rather have real image files.
• Extracted files are lighter and more portable for a docs repo, but now you're managing an images/ folder alongside your Markdown.

md-convert's tool inlines images as base64 by default (with a sane cap — after roughly 20 images or 4MB total, additional images are swapped for a placeholder rather than silently bloating the output), which is the right tradeoff for a quick one-off conversion. If you're scripting a batch job for a documentation repo, extracting to real files is usually worth the extra step — the Python example below does exactly that.

Tables convert to GitHub Flavored Markdown pipe tables, with the first row treated as the header and a --- divider row generated beneath it. The catch is merged cells: Markdown's table syntax has no concept of a cell spanning two columns or two rows, so a merged header gets flattened — usually repeated across the columns it used to span, or left blank in the extra cells. If your source table relies heavily on merged cells, expect to hand-check that section after conversion; no converter, browser-based or CLI, reconstructs a merge that Markdown has no syntax for.

For Developers: Converting DOCX to Markdown with Python

If you're converting more than a handful of files — a documentation migration, a nightly export job — scripting it is worth the ten minutes of setup. markitdown, Microsoft's open-source conversion library, is a solid default: it's free, actively maintained, and handles Word documents alongside PDFs, spreadsheets, and PowerPoint decks with the same API.

Install it:

bash

pip install "markitdown[all]"

Convert a single file:

python

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("migration-checklist.docx")

with open("migration-checklist.md", "w", encoding="utf-8") as f:
    f.write(result.text_content)

And for a folder full of documents:

python

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown()
input_dir = Path("docs")
output_dir = Path("markdown")
output_dir.mkdir(exist_ok=True)

for docx_path in input_dir.glob("*.docx"):
    result = md.convert(str(docx_path))
    (output_dir / f"{docx_path.stem}.md").write_text(
        result.text_content, encoding="utf-8"
    )

Point this at a folder of legacy specs or onboarding docs and it'll churn through all of them in one run. It's not the only library out there — python-docx gives you lower-level control if you need custom style mapping — but markitdown covers the common case with the least code, and it's entirely open source, so there's no license to negotiate before you drop it into a CI pipeline.

Beyond DOCX: The Rest of Your Document Pipeline

Word files are rarely the only thing you're dealing with. A typical migration also has PDFs from vendors, HTML pages you're archiving, and CSVs you need in a readable format. Rather than hunting down a separate tool for each one, md-convert.org's toolbox of 16 free converters covers PDF, HTML, JSON, CSV, YAML, Jupyter notebooks, and more, all running the same privacy-first, browser-only approach as the DOCX converter. If PDFs are also part of your stack, the PDF to Markdown guide covers the OCR and layout-parsing side of that problem in more depth.

It's also worth knowing the workflow runs the other way. Once your content lives in Markdown, you'll eventually need to hand someone a .docx for tracked changes, or a clean PDF for a client — and Word doesn't read .md natively any more than it reads it now. For that direction, see our guide on converting Markdown back to Word, PDF or HTML, including the markdown to docx command in Pandoc.

One more Word-specific trick worth knowing: if you'd rather avoid the DOCX/OOXML layer entirely, Word's File → Save As → Web Page, Filtered export gives you an HTML file with most of the XML cruft already stripped out, which you can then run through an HTML to Markdown converter for a slightly different (and sometimes cleaner) result on documents with unusual formatting.

Frequently Asked Questions

How do I convert .docx to Markdown without losing tables?

Use a converter that outputs GitHub Flavored Markdown pipe tables, like Pandoc (pandoc file.docx -t gfm -o file.md) or md-convert's browser tool, and keep source tables simple. Merged cells don't have a Markdown equivalent, so tables without merges convert cleanly; tables with merged headers will need a manual check afterward.

Can I convert Word to Markdown with embedded images?

Yes. Browser tools like md-convert embed images as base64 data URIs automatically, so the result is a single self-contained file. For a documentation repo where you'd rather have separate image files, Pandoc's --extract-media flag or a Python script using markitdown will pull images out into a real folder and reference them by path instead.

How does this compare to Pandoc?

Pandoc is more configurable — custom writers, reference templates, fine-grained footnote and citation handling — and it's the better choice for scripted, high-volume conversions. The tradeoff is that it needs to be installed and run from a terminal. A browser-based converter needs nothing installed and works on a locked-down machine, which makes it faster for a single file or an occasional conversion.

Try It on Your Next Document

The real fix here isn't a trick for cleaner copy-pasting — it's skipping the paste entirely and converting properly instead. For a script-driven pipeline, markitdown or Pandoc will do the heavy lifting. For everything else, md-convert's DOCX to Markdown tool gets you a clean .md file in about the time it takes to drag a file into a browser tab — free, no sign-up, and nothing ever leaves your device.