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
A `.docx` file is not a document — it is a ZIP archive containing a small filesystem of XML parts, standardised as ECMA-376 and later ISO/IEC 29500. Unzip one and you will find `word/document.xml` holding the body content, `word/styles.xml` defining the named styles, `word/numbering.xml` describing list formats, `word/_rels/` wiring up relationships, and a `media/` folder holding any embedded images.
This structure is what makes DOCX the most faithfully convertible of all the common input formats. Unlike PDF, where a heading is inferred from how large the text happens to be, WordprocessingML records intent directly: a paragraph carries a `pStyle` reference naming the style applied to it. A paragraph styled `Heading 2` is semantically a level-two heading, and that mapping to Markdown's `##` is exact rather than heuristic.
Mammoth.js is built specifically around that insight. Rather than trying to reproduce Word's visual appearance, it maps Word's semantic style names onto clean HTML, which is then converted to Markdown. The consequence worth understanding is that conversion quality depends on how the original document was authored: a document that uses real heading styles converts near-perfectly, while one where the author simulated headings by manually bolding text and increasing the font size has no semantic information to recover.
What maps cleanly, and why
Headings map exactly. Word's built-in `Heading 1` through `Heading 6` styles become ATX headings `#` through `######`, because the style name states the level. Emphasis maps directly too: a run with the `<w:b/>` property becomes `**bold**`, `<w:i/>` becomes `*italic*`, and combined runs nest correctly.
Lists carry more information than they appear to. `numbering.xml` records both the list's format (bullet, decimal, lower-roman) and each paragraph's indentation level, so ordered and unordered lists convert with their nesting preserved rather than being flattened to a single level. Tables convert to GitHub Flavored Markdown pipe tables with the header row retained, since WordprocessingML marks header rows explicitly.
Hyperlinks resolve through the relationships file: the link text lives in the document body while the target URL lives in `word/_rels/document.xml.rels`, and the converter joins them to emit standard `[text](url)` syntax. Footnotes and endnotes are collected and appended, and block quotes styled with Word's `Quote` style become `>` blockquotes.
What cannot survive, and why that is inherent
Markdown is a semantic, flow-based format with a deliberately small vocabulary. Anything in a Word document that describes visual placement rather than meaning has no target to map onto, and the loss is a property of Markdown rather than a limitation of the converter.
Page headers and footers, page numbers, section breaks, columns, text boxes and absolutely positioned floating elements all fall into this category — Markdown has no page model at all, so there is nowhere to put them. Fonts, colours, character spacing and highlight shading are presentational and are dropped. Comments and tracked changes are review metadata stored in separate XML parts; they are not part of the document body and are not emitted.
Embedded images are a partial case. Mammoth extracts them as base64 data URIs, so they render inline and remain self-contained, but the result is verbose and most static site generators would prefer real image files with relative paths. For image-heavy documents, expect to extract the media folder from the ZIP separately and rewrite the paths.
Why authoring style determines conversion quality
The most common disappointment with DOCX conversion has nothing to do with the converter: it is a document where the author never used heading styles. If a section title is a normal paragraph that has been manually set to 16pt bold, then structurally it is a normal paragraph, and it converts to a bold line of body text rather than a heading. The visual cue that a human reads as a heading was never recorded as one.
The same applies to lists typed as literal hyphens or manually numbered `1.`, `2.`, `3.` in body text, and to layout achieved with tabs and empty paragraphs rather than styles and spacing. None of it carries semantics, so none of it can be recovered.
If you control the source document and the conversion matters, the fix takes a few minutes: apply real heading styles from the Styles gallery, use the list buttons rather than typing markers, and delete manual spacing. A document authored this way converts essentially losslessly, and the same discipline makes it more accessible and easier to navigate in Word too.
Legacy .doc files and other Word formats
Only the modern `.docx` format is supported. The legacy `.doc` extension is an entirely different, undocumented binary format from the pre-2007 era with no relationship to OOXML — it is not a ZIP archive and contains no XML, so nothing in this pipeline can read it. Open it in Word or LibreOffice and save as `.docx` first; the conversion is lossless and takes seconds.
Macro-enabled `.docm` files use the same OOXML structure as `.docx` with an additional VBA part, so their body content is readable in principle, but they are not accepted here — refusing to open files that carry executable payloads is the safer default. `.dotx` templates and `.rtf` are also distinct formats; RTF has its own converter on this site.
Privacy implications for confidential documents
Word documents are disproportionately likely to be sensitive: contracts, offer letters, board minutes, patient summaries, unpublished manuscripts. They also frequently carry more than their visible content — author names, revision history, editing time, and file paths from the machine they were created on all live in the document's metadata parts.
Because the conversion runs entirely inside your browser tab, none of that is transmitted. The file is read with the FileReader API, unzipped in memory, parsed in a Web Worker on your own CPU, and discarded when you close the tab. There is no upload endpoint, no server-side temporary copy, and nothing to request deletion of afterwards. You can verify this directly: open your browser's Network panel and convert a document — no request carries the file.
Known limitations of DOCX to Markdown conversion
Being explicit about what a converter cannot do saves you a wasted upload. These are the boundaries of what is recoverable from DOCX programmatically:
- Legacy binary `.doc` files are not supported; re-save as `.docx` first. Macro-enabled `.docm` is also declined by design.
- Page headers, footers, page numbers, section breaks and multi-column layouts have no Markdown equivalent and are dropped.
- Comments and tracked changes live in separate XML parts and are not part of the converted body.
- Embedded images become base64 data URIs, which is self-contained but verbose; static site pipelines usually want extracted files instead.
- Manually formatted pseudo-headings (bold, enlarged body text) convert as emphasis, not headings — there is no semantic style to read.
- Fonts, colours, highlighting and character spacing are presentational and are not represented in Markdown.
Who Converts DOCX to Markdown?
Technical Writers
Migrating a documentation set out of Word and into a docs-as-code pipeline, where Markdown lives in Git alongside the product it documents.
Developers
Turning a specification or requirements document received from a stakeholder into a Markdown file that can be diffed, reviewed and linked from issues.
Academics & Students
Moving a thesis chapter or paper draft into Obsidian or a plain-text writing workflow while keeping heading structure, emphasis and footnotes intact.
Content teams
Importing articles delivered as Word attachments into a static site generator or headless CMS without hand-retyping the formatting.
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.
Off the main thread
Heavy parsing is dispatched to a Web Worker, so a 500-page PDF or a large spreadsheet never freezes the interface. 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.
DOCX to Markdown — FAQ
Which Word formatting survives the conversion to Markdown?
Headings 1–6, ordered and unordered lists including nesting, bold and italic emphasis, hyperlinks, blockquotes, tables and embedded images are converted. Decorative formatting — font families, colours, sizes, text boxes, and Word's page layout — is deliberately dropped, because Markdown has no way to express it.
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.
Is my Word document uploaded to a server?
No. The .docx is parsed on your device inside a Web Worker, so confidential contracts and internal reports never cross the network. You can verify it in the DevTools Network panel while converting.
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.