Convert Word DOCX to Markdown
Convert Word documents to Markdown keeping headings, lists, links, bold, italic and tables, with configurable heading and bullet styles.
- Runs in your browser
- Files are never uploaded
- Free, no account
Off keeps the Markdown small and skips pictures entirely.
How to convert Word to Markdown
- Drop your
.docxfiles. Several at once is fine; you can switch between them afterwards. - Pick your Markdown dialect. ATX or setext headings, hyphen/asterisk/plus bullets, fenced or indented code, underscore or asterisk emphasis.
- Decide about images. Off keeps the file small; on inlines each picture as a base64 data URI so the Markdown is self-contained.
- Review and download. The second tab shows the intermediate HTML, which makes any surprise easy to trace.
How the conversion works
It is a two-stage pipeline, and knowing that explains most of the results. First
mammoth unzips the .docx and maps Word’s semantic styles onto HTML —
“Heading 2” becomes <h2>, a list paragraph becomes <li>, a
hyperlink becomes <a>. Then Turndown converts that HTML into
Markdown using the style options you chose. Both stages run in this browser tab.
The important consequence: mammoth maps styles, not appearance. A line that merely looks like a heading because someone made it 18pt and bold is still a paragraph, so it comes out as body text. If your headings are missing, apply real heading styles in Word and convert again — that is usually a two-minute fix and it also makes the document accessible.
Element mapping
| In Word | In Markdown |
|---|---|
| Heading 1-6, Title, Subtitle | # … ###### |
| Bulleted list, including nesting | - with two-space indents |
| Numbered list | 1., 2., … |
| Bold / italic / strikethrough | **bold**, _italic_, ~~struck~~ |
| Hyperlink | [text](url) |
| Quote / Intense Quote style | > blockquote |
| Table | GitHub pipe table with an alignment row |
| Inline code character style | `code` |
| Fonts, colours, point sizes | Dropped — Markdown has no equivalent |
| Footnotes, comments, tracked changes | Not converted |
Tables
Word tables become GitHub-flavoured pipe tables. The first row is promoted to the header — which is what
almost every real document intends — and any cell alignment is written into the divider row as
:---, ---: or :---:. Line breaks inside a cell become
<br>, because a Markdown table row cannot span lines, and pipe characters in the text
are escaped so the columns stay intact. Merged cells cannot be represented, so a merged cell contributes
its value once and the covered positions are left empty.
About images
Word stores pictures inside the document package, so there is no URL to link to. Two honest options exist: embed each image as a base64 data URI, which keeps everything in one file but can multiply its size several times over, or omit them. Embedding is off by default; the tool warns you when the result grows past a megabyte. Changing this setting re-reads the documents, because the decision is made while mammoth walks the file.
Typical uses
- Moving documentation out of Word and into a Git repository, a wiki or a static site generator.
- Turning a client-supplied brief into content for a CMS that speaks Markdown.
- Making documents diffable so changes between versions are reviewable in a pull request.
- Batch-migrating a folder of specs — drop them all and download one ZIP.
Questions
Which Word features survive the conversion?
Heading levels 1-6, ordered and unordered lists with nesting, hyperlinks, bold, italic, strikethrough, blockquotes, inline code and tables all map onto Markdown equivalents.
How are Word tables converted?
Into GitHub-flavoured Markdown tables, with the first row promoted to the header and any cell alignment preserved in the divider row. Cell line breaks become <br>.
What happens to images in the document?
Off by default, so the Markdown stays small. Turn on image embedding and each picture is inlined as a base64 data URI, which keeps the file self-contained but much larger.
Why does my styled text lose its formatting?
Markdown has no concept of fonts, colours or sizes. Only structural formatting maps across — direct formatting such as “red 14pt Calibri” is intentionally dropped.
Can I see the intermediate HTML?
Yes. The second tab shows the HTML that mammoth produced before Turndown converted it, which makes odd output much easier to diagnose.