Word to Markdown: Two Clean Paths and What Survives the Conversion

Converting a Word document to Markdown by copy-paste never works: bold survives as stray formatting, tables become screenshots, and every heading level flattens. There are two clean routes — pandoc on the command line (batch, scriptable) and in-browser local conversion (zero install, the file never leaves your machine). Both face the same set of format-model problems; this post walks through each one. In a hurry? The Word to Markdown tool does the whole conversion in your browser, with no upload.

Why copy-paste is never clean

Word's document model is style-driven: text "looks like a heading" either because it carries a Heading 2 style or because someone manually enlarged and bolded it. Markdown is semantic: ## is a level-2 heading; there is no "looks like".

Conversion is therefore an act of semantic guessing: the converter must decide whether that big bold text is truly a heading. Both pandoc and browser tools walk the same path — parse the docx into semantic HTML, then map that down to Markdown. The more manual formatting a document accumulated, the harder the guessing gets.

Route one: pandoc (CLI, for batches)

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

• -t gfm emits GitHub Flavored Markdown — the best compatibility for tables, strikethrough, and task lists;
• --extract-media=./assets pulls images into a local folder instead of inlining them;
• batch: for f in *.docx; do pandoc "$f" -t gfm -o "${f%.docx}.md"; done

This is the right route for editorial teams and static-site migrations processing hundreds of documents once.

Route two: in-browser local conversion (for sensitive documents)

Contracts, internal review drafts, unreleased plans — anything you should not hand to a third-party online converter. The browser-local route does all computation on your own machine and works with the network unplugged:

1. Open the docx to Markdown tool;
2. Drop in a .docx file (Word 2007 or newer);
3. Pick an image strategy (inline, or drop to placeholders);
4. Copy the result or download the .md.

Your document is never uploaded — that's not a promise, it's the architecture: the entire pipeline runs inside your browser process, and there is no backend that could receive the file. For the reverse direction (Markdown back to a Word deliverable), the Markdown to Word tool runs equally locally.

Format fidelity table

The three most common traps

Trap one: legacy .doc fails immediately

.doc is the binary OLE format; .docx is OOXML — a zip of XML. Two different eras. Every modern converter consumes OOXML only: open the .doc in Word or WPS and "Save as .docx" first. The tool rejects .doc with a message pointing at exactly this path, rather than silently producing garbage.

Trap two: images blow up the file

Inlining images as base64 makes a single self-contained .md, but a 2 MB screenshot becomes ~2.7 MB of base64; ten images yield a document that chokes editors and bloats git repos. Rule of thumb: inline for self-contained one-offs, extract to an assets folder for anything under version control.

Trap three: auto-numbering becomes hardcoded numbers

Word's auto-numbering is "style + counter"; after conversion you get literal 1. 2. 3.. It looks identical, but inserting an item in Word renumbered everything downstream, while the Markdown now needs manual renumbering. This is a fundamental model difference, not a bug — just know it going in.

Implementer's note

The browser tool's pipeline is mammoth (docx → semantic HTML) + turndown with the GFM plugin (HTML → Markdown), and both libraries are dynamically imported — the page loads instantly without the conversion code; the libraries are fetched the moment a file is dropped. The image toggle defaults to "keep": inline base64 is heavy, but "the file you forwarded shows broken images" hurts more than "the file is big". mammoth's conversion warnings (unsupported elements that were dropped) pass through to the results pane unfiltered — you deserve to know what was lost. The .doc rejection copy spells out the escape hatch (re-save as .docx), because "error + directions" beats silent degradation.

FAQ

My converted table is mangled. What now?

Almost certainly merged cells. Markdown tables (GFM included) don't support rowspan/colspan — either split into several simple tables, keep the table as an image, or drop in an embedded HTML table.

Do equations convert?

pandoc can turn OMML equations into LaTeX (use the --to markdown dialect); the browser route has essentially no math support. For equation-heavy documents, rewriting in LaTeX/Typst is the honest recommendation.

Will a 100-page document freeze the tab?

Browser-local parsing of a docx tens of MB in size is fine — the bottleneck is your editor opening the resulting giant .md. Split long documents by chapter before converting. For PDF-side processing (merge/split/compress), the PDF tools guide covers that pipeline.

Does it upload my file?

No. The conversion code runs in your browser; file contents never leave the machine. Verify it yourself: unplug the network and the tool still works end to end.

These conversion notes come from building the document-conversion tools at ToolVault; every route difference described here was tested during development.

Field note

mammoth's docx→HTML style mapping is sensitive to locale-specific style names ("Heading 1" vs localized equivalents), and WPS-produced files occasionally carry proprietary style names. Rather than enumerate mappings, the tool leans on mammoth's outline-level heuristics as a fallback — good coverage on mainstream templates in testing, with residual unknown styles surfaced as warnings for human review.