Word to Markdown: 4 Ways to Convert .docx Files and Online Docs (Tested)

If you write in Microsoft Word but your work ends up in ChatGPT, Claude, Cursor, a static site, or a Git repo, you need a reliable way to go from Word to Markdown. I tested four methods on the same file: a 14-page product spec with nested lists, two tables, inline code, and a few images. They gave very different results.

One thing up front: Web2MD is a Chrome extension that converts web pages to Markdown. It does not open a .docx file sitting on your hard drive. If your Word document is local, Pandoc or Mammoth is the right tool, and I explain both below. Web2MD helps when the document is already open in a browser tab, such as Word Online, SharePoint, Google Docs, or a Confluence page someone exported from Word. That covers most of the documents I deal with at work.

Why bother converting Word to Markdown?

Three practical reasons:

1. AI tools read Markdown better than pasted rich text. When you paste from Word into ChatGPT, the heading structure often disappears and tables turn into tab-separated text. With Markdown, the model can see that a line is an H2 and not just a bold sentence.
2. Token cost. Raw HTML exported from Word is full of mso- style attributes. In my test file, the "Save as Web Page" HTML was roughly 6x the token count of the equivalent Markdown.
3. Version control. You can diff Markdown in Git. You cannot meaningfully diff a .docx.

Method 1: Pandoc (best for local .docx files)

Pandoc is the standard tool, and for good reason. It is free and open source, and it handles almost everything Word throws at it.

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

The -t gfm flag outputs GitHub-Flavored Markdown, which gives you pipe tables. --extract-media saves embedded images to a folder and rewrites the image links.

What I saw:

• Headings mapped correctly, as long as the author used real Word heading styles. If they made "headings" by bolding Normal text and bumping the font size, Pandoc outputs bold paragraphs, which is correct behavior but probably not what you want.
• Simple tables came out as clean pipe tables. A table with merged cells fell back to raw HTML, because GFM has no syntax for merged cells.
• Tracked changes are accepted by default. Use --track-changes=all if you need to see them.

Limits: it is a command-line tool, so non-technical teammates often won't use it.

Method 2: Mammoth (good for clean semantic output)

Mammoth is a JavaScript/Python library built specifically for .docx. It deliberately ignores visual formatting and keeps only meaning: headings, lists, bold, links.

npx mammoth spec.docx --output-format=markdown

The output was a little cleaner than Pandoc for prose-heavy documents. Tables were weaker, though: Mammoth's Markdown output flattened mine into paragraphs. The Mammoth maintainers recommend HTML output for anything table-heavy, which says a lot.

Method 3: Word Online or SharePoint plus Web2MD (for docs you only have in a browser)

This is the case the first two methods miss. A lot of Word documents never touch your disk. They live in OneDrive, SharePoint, Teams, or a company wiki, and you only have view access behind a login.

Server-side converters like Jina Reader and Firecrawl are excellent for public URLs. Jina's r.jina.ai prefix is the fastest way I know to turn a public article into Markdown, and Firecrawl handles crawling at scale far better than any browser extension. But both fetch the page from their own servers, so they hit your company login wall and return a sign-in page.

Web2MD runs inside your browser, so it sees exactly what you see. I opened the spec in the browser view of SharePoint, clicked the extension, and got this:

# Checkout Service v2 Spec

## 1. Goals

- Reduce payment step latency below 800 ms at p95
- Support saved cards for logged-in users
  - Tokenized via the existing vault
  - No raw PAN stored in our database

## 2. API Changes

| Endpoint            | Method | Change          |
|---------------------|--------|-----------------|
| /v2/checkout        | POST   | New             |
| /v1/checkout        | POST   | Deprecated Q1   |

> Note: the v1 endpoint stays live for 90 days after launch.

Token count: 1,842 (cl100k)

Honest notes from testing:

• The browser view matters. Word Online's editing view renders the document in a heavily scripted canvas. The reading or embed view gives much cleaner output. If the result looks thin, switch views and convert again.
• Merged table cells came out as a regular grid with the merged content repeated. That is readable for an AI model but not perfect.
• Images are kept as links to the hosted image URLs, not downloaded. Those URLs usually need your session, so they won't render outside your account.
• The built-in token counter showed 1,842 tokens before I sent anything. That was useful because I was about to paste three of these specs into one Claude conversation.

Since everything happens locally in the browser, the document content is not sent to a third-party conversion server. For internal specs that is the main reason I use this method rather than uploading to an online converter.

Limits: Chrome only (plus Chromium browsers like Edge and Brave). The free tier is 3 conversions per day, with no account or API key needed. Pro is $9/month for unlimited conversions. For bulk-converting a folder of 200 local .docx files, use Pandoc in a shell loop instead. That is a better fit for the job.

Method 4: Copy and paste into a Markdown editor

Some editors, such as Typora, Obsidian with a paste plugin, and Notion (followed by a Markdown export), convert rich text on paste. It works for a page or two. In my test, nested lists lost a level of indentation and both tables needed manual cleanup. It's fine for a quick note and painful for anything longer.

Which method should you use?

| Your situation | Best tool | |---|---| | Local .docx, need high fidelity | Pandoc | | Local .docx, mostly prose, want minimal markup | Mammoth | | Doc lives behind a login (SharePoint, Word Online, Confluence) | Web2MD | | Public web page version of the doc | Jina Reader or Web2MD | | Hundreds of files, scripted | Pandoc | | One paragraph, right now | Copy and paste |

Tips that improved every method

• Use real heading styles in Word. Every converter depends on them. Fixing styles in the source took me five minutes and saved more cleanup than any tool setting.
• Avoid merged cells if the output is headed for Markdown. Split them, or accept HTML tables.
• Check the token count before pasting into an AI tool. A long Word doc can quietly eat a large share of your context window. Web2MD shows the count at conversion time. For Pandoc output, any tokenizer will do.
• Strip the boilerplate. Cover pages, revision tables, and legal footers use tokens and add nothing for the model. Delete them from the Markdown before sending.

Wrapping up

There is no single best Word to Markdown converter, because "Word document" covers two different things: a file on your disk and a page in your browser. For files, Pandoc is hard to beat. For documents you can only reach after logging in, a browser-side tool is the only kind that can actually see the content.

If the second case sounds familiar, you can try Web2MD free. Three conversions a day are enough to check whether it fits your workflow. For more on getting clean context into AI tools, browse the rest of the Web2MD blog.