DOCX to Markdown
Convert DOCX to Markdown with ATX headings, hyphen bullets, working links and GFM pipe tables. Copy the output or save it as a .md file under the original name.
Runs entirely in your browser — your files and text never leave your device.
Drag & drop your file here, or
How to use
- Drop the Word file on the dropzone. Choose file works too if you'd rather browse for it.
- Press Convert to Markdown. The status line beside the button reads Done when the document has been read.
- Read the top of the Markdown pane first. If your document title came out as ordinary text instead of a # line, it was styled Title in Word rather than Heading 1.
- Use the copy button for a paste into a README or a CMS, or Download .md to get a file. The download keeps your filename, so handbook.docx saves as handbook.md.
- If a table came through as raw HTML, open it in Word, tick Repeat as header row on the top row under Table Properties, and convert again.
About this tool
Docs get drafted in Word and published in Markdown, and the gap between the two is where afternoons go. DOCX to Markdown closes it. Mammoth reads the real structure out of the .docx, then Turndown writes that back as GitHub-Flavored Markdown: headings become # lines, bullets become hyphens, links keep their URLs, and a table whose top row is marked as a header becomes a pipe table.
The thing worth knowing is that the conversion follows Word's paragraph styles rather than how the page looks. Text that is bold and 18pt is still a paragraph. Text styled Heading 2 is a heading even if someone shrank it to 11pt. A document built with the style menu converts almost perfectly. One formatted by eye comes out flat, and the fix for that is upstream in Word. If you want the intermediate HTML instead, DOCX to HTML stops at that step, and DOCX to Text drops the markup altogether.
What comes out the other side
Take a Word file with a Heading 1 called Onboarding, two Heading 2 sections under it, a bulleted list in each, and a three-column table whose top row is set to repeat as a header. Convert it and you get # Onboarding, two ## lines, hyphen bullets underneath, and a pipe table with a row of dashes separating the header from the body.
Now untick the repeat-as-header box on that table in Word and convert the same document again. Everything else reads the same, but the table comes back as a raw HTML block instead. That one checkbox is the whole difference between a pipe table and a lump of markup, and it catches people out more than anything else here.
Good to know
- Images arrive as base64 data URIs, so a single screenshot can become several hundred kilobytes of one unbroken line sitting in the middle of your Markdown. For picture-heavy documents, delete those lines and add the images back as files.
- Underline is dropped without a warning, because Mammoth has no default tag for it and Markdown has no syntax for it either. Colored text, fonts, columns and text boxes go the same way. Bold, italic and strikethrough all survive.
Frequently asked questions
Why did my Word tables come out as raw HTML?
Turndown only writes a pipe table when every cell in the first row is a header cell, and Mammoth only marks a row that way when Word's own repeat-header flag is set on it. Open Table Properties, go to the Row tab, tick Repeat as header row at the top of each page, then convert again. Tables without that flag are passed through as HTML, which GitHub still renders, just less tidily.
Which flavour of Markdown does it write?
GitHub-Flavored. Headings use the ATX style, # through ######. Bullets use a hyphen rather than an asterisk. Strikethrough survives as two tildes either side of the text, and tables become pipe tables when the header row qualifies.
My document title is plain text at the top of the output. What happened?
Mammoth maps Heading 1 through Heading 6 onto # through ######. Word keeps Title as a separate style, and the default map has no entry for it, so a Title paragraph lands as an ordinary paragraph. Restyle it as Heading 1 in Word and it converts to a single # line.
It says my file is a legacy .doc. What does that mean?
A .docx is really a ZIP archive, so the tool checks the first two bytes for the PK signature every ZIP starts with. A Word 97–2003 .doc is a different binary format with no reader here. Open it in Word, Google Docs or LibreOffice, use Save As to make a .docx, and bring that file back.
Can I paste the result straight into a README?
That is what the hyphen bullets and ATX headings are set up for. Paste it into README.md and GitHub renders it as written. Worth one skim first for stray data-URI image lines, which are long enough on their own to make a diff unreadable.
Missing something in DOCX to Markdown? Suggest a feature →