Convert Word DOCX Documents to Markdown
docx to md without the Word XML noise. Mammoth.js reads the WordprocessingML inside the .docx ZIP, maps each paragraph’s pStyle to its semantic equivalent, and the resulting HTML is sanitised and turned into clean CommonMark/GFM — entirely inside your browser.Processing happens 100% in your browser — nothing is uploaded.
How to convert DOCX to Markdown
- Drop the file: drag your .docx onto the dropzone, or click to browse. The file is read locally and never uploaded.
- Local processing: Mammoth.js unzips the document parts and maps Word's named styles to semantic HTML, which is sanitised and converted to Markdown by Turndown in a Web Worker.
- Copy or download: copy the Markdown, or save it as a .md file ready for Git, a static site generator or your docs repo.
Why Convert DOCX to Markdown with MD Convert?
Heading levels mapped from styles, not font sizes
WordprocessingML records intent: a paragraph carrying a Heading 2 pStyle is semantically a level-two heading, so the mapping to ## is exact rather than inferred from how large the text happens to be. Headings 1–6, nested ordered and unordered lists, bold, italics, links and blockquotes all carry across.
Word XML bloat discarded, not translated
The w:p and w:r run-splitting Word uses to record edit history, plus revision IDs, language tags, theme fonts and colour attributes, have no meaning in Markdown and are dropped. What survives is structure and emphasis — portable, diff-able, editor-agnostic output.
Tables emitted as valid GFM pipe tables
The first row of every table becomes the header row with a --- divider beneath it, whether or not the document set 'Repeat as header row'. Pipe characters inside cells are escaped and in-cell newlines collapse to spaces, because a pipe table with a broken divider is not a table at all.
Confidential contracts never leave your device
The .docx is read with the browser's own File APIs and parsed in a Web Worker. Nothing is uploaded, so NDAs, legal drafts, HR documents and unpublished manuscripts stay on your machine. Embedded HTML is sanitised with DOMPurify before conversion, so a booby-trapped document cannot inject anything into the preview.
DOCX to Markdown: Before and After
The XML body of a Word document, and the Markdown it produces. Note that `pStyle` names the heading level explicitly; nothing is inferred from font size.
<w:p>
<w:pPr><w:pStyle w:val="Heading1"/></w:pPr>
<w:r><w:t>Quarterly Review</w:t></w:r>
</w:p>
<w:p>
<w:r><w:t xml:space="preserve">Throughput improved </w:t></w:r>
<w:r><w:rPr><w:b/></w:rPr><w:t>34%</w:t></w:r>
<w:r><w:t> after the Worker migration.</w:t></w:r>
</w:p>
<w:p>
<w:pPr><w:numPr><w:ilvl w:val="0"/></w:numPr></w:pPr>
<w:r><w:t>Ship streaming extraction</w:t></w:r>
</w:p># Quarterly Review
Throughput improved **34%** after the Worker migration.
- Ship streaming extractionUnderstanding the DOCX Format: ECMA-376 / ISO/IEC 29500
- Format
- Office Open XML (WordprocessingML)
- Specification
- ECMA-376 / ISO/IEC 29500
- Media type
application/vnd.openxmlformats-officedocument.wordprocessingml.document- Parser used
- Mammoth.js
Technical Specifications & Style Mapping Rules
- Semantic styles vs. manual styling: Word Heading 1 to Heading 6 styles map cleanly to # through ######. Body text that is only manually enlarged or bolded converts as plain text with emphasis, because no heading style is recorded. Apply native Word styles before converting.
- Tables and lists: the first row of each table becomes the GFM header row. Nested bullet and numbered lists keep their hierarchy. Newlines inside a cell collapse to spaces, because a GFM table cell cannot hold a line break.
- Legacy .doc and macro formats: binary .doc files and macro-enabled .docm files are declined, for security and compatibility. Save the file as .docx in Word or LibreOffice first.
- Presentational elements: page headers, footers, margins, multi-column layouts and drawing shapes have no Markdown equivalent and are dropped. Comments and tracked changes are stored in separate parts and are not emitted.
- Embedded images: inlined as base64 data URIs, so the Markdown stays self-contained. For media-heavy documentation pipelines, extract the assets separately with the CLI route below.
Developer Alternative: Pandoc CLI & Python Extraction
For scripted or high-volume conversion, Pandoc and the Python Mammoth binding produce Markdown from the same WordprocessingML. Pandoc can also extract images into a real folder, which the browser route does not do.
# Canonical Pandoc conversion with media extraction
pandoc -f docx -t gfm input.docx -o output.md --extract-media=./media# Fast, clean DOCX to Markdown conversion using Python Mammoth
import mammoth
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_markdown(docx_file)
markdown_text = result.value
print(markdown_text)How You Can Verify the Privacy Claim
Zero server upload
Conversion runs inside your browser tab. Open DevTools, switch to the Network panel, and convert a file: for every format except URL to Markdown you will see no request carrying your document — because there is no endpoint to send it to.
Parses on the main thread
Parsing stays inside your browser tab — this format’s parser needs DOM APIs. Nothing is uploaded. Everything is plain JavaScript — no native plugin, no WebAssembly toolchain, nothing to install.
Nothing to sign up for
No login, no quota, no paywall, and no tracking tied to your files. Analytics are cookieless and aggregate only. Read the privacy policy for the full data-flow breakdown, including the one proxied exception.
The parsers doing the work
No proprietary black box: each format is handled by a widely audited open-source library, running client-side at the version pinned in our lockfile.
- Mammoth.js (WordprocessingML style mapping)WordprocessingML style mapping
- Turndown (HTML to Markdown)HTML to Markdown
- DOMPurify (HTML sanitisation)HTML sanitisation
DOCX to Markdown — FAQ
Why did my headings come out as plain paragraphs?
Because the document simulated headings instead of using them. If the author bolded a line and increased the font size rather than applying the Heading 1 style, the file contains no semantic heading for the converter to find. Applying real heading styles in Word and re-exporting fixes it — conversion quality is a function of how the source was authored.
Are images inside the DOCX preserved?
Yes. Embedded images are inlined as base64 data URIs so the Markdown stays self-contained with no sidecar files. There is a deliberate budget — up to 20 images and roughly 4 MB total — beyond which further images are replaced with a placeholder and a warning is shown, because a document full of screenshots would otherwise produce tens of megabytes of base64 text.
How does this compare to Pandoc for docx to md conversion?
Pandoc is more configurable — custom writers, reference docs, footnote and citation handling — but it has to be installed and run on the command line. This converter needs only a browser tab, which makes it faster for one-off conversions and usable on a locked-down machine where you cannot install software or upload the file.
Does it support the legacy .doc format?
No. It targets modern .docx (Office Open XML, ECMA-376). Legacy binary .doc files use an entirely different structure — open one in Word or LibreOffice and save it as .docx first.