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.
Word file
Drop a .docx here
Word 2007 and later · one file at a time · nothing is uploaded
—
—
What the document carries
What the converter reported
Output view
Tables, mapping and pictures
Preview
Converted
How to use
- Drop the Word file on the dropzone, or use Choose file. The Markdown appears straight away — there is nothing to press.
- Read the list of what the document carries. Anything tagged dropped or unread is named there, word for word where it can be.
- Leave Cells unwrapped and Title as heading on for tables and a title that convert properly. Turn on Images as files when a screenshot would otherwise become one enormous line.
- Switch the view to Preview to see the file rendered before you paste it anywhere.
- Press Copy Markdown for a README or a CMS, or download it. The file keeps your document's name, so handbook.docx saves as handbook.md, or handbook.zip when the pictures travel as files.
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 the moment the file lands. Mammoth reads the real structure out of the .docx, then Turndown writes it back as GitHub-Flavored Markdown: headings become # lines, bullets become hyphens, links keep their URLs, and every table becomes a pipe table with its first row as the header.
Above the result sits a list of what the document carries, part by part, with what Markdown keeps of each. That is where you find out before pasting that an underlined phrase lost its line, or that the header and footer were never read. The conversion follows Word's paragraph styles rather than how the page looks, so text styled Heading 2 is a heading even at 11pt, while bold 18pt text is still a paragraph. 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 handbook with a Heading 1 called Onboarding, a Heading 2 under it, a bulleted list with one nested point, two numbered steps and a three-by-three table of regions and revenue. Drop it and the well holds # Onboarding, a ## line, hyphen bullets indented by level, 1. and 2., and a pipe table whose top row, Region · Revenue · Change, sits above a row of dashes.
The same file has one underlined word and a footer reading Page 1 of 1. The list says both out loud: the underline is dropped because Markdown has no syntax for it, and the footer is not read because Mammoth never opens it. Neither is a surprise in a pull request later.
Good to know
- Underline has no Markdown syntax, so underlined words keep their text and lose the line. Coloured text, fonts, columns and text boxes go the same way. Bold, italic and strikethrough all survive.
- Headers, footers and comments live in separate parts of the .docx that Mammoth does not read. The list names the header and footer text it found there, ready to copy across by hand.
Frequently asked questions
How do Word tables come out?
As pipe tables, one row per line, with the first row used as the header. Word tables almost never mark a header row, and a cell's text sits in its own paragraph, so with Cells unwrapped on each cell's paragraphs are joined with a <br> and the top row becomes the header. Turn the switch off and a table without a header row stays as raw HTML.
Which flavour of Markdown does it write?
GitHub-Flavored. Headings use the ATX style, # through ######. Bullets use a hyphen. Strikethrough is two tildes either side of the text, which GitHub, GitLab and markdown-it all render. Tables are pipe tables.
My document title came out as plain text. What happened?
Word keeps Title as its own style, separate from Heading 1, and Mammoth's default map has no entry for it. Title as heading adds that entry, so a Title paragraph becomes a single # line. With the switch off, the converter's own warning about the unrecognised style is listed under the document's contents.
What happens to pictures?
By default each picture is written inline as a data URI, which keeps the .md self-contained but turns a screenshot into one very long line. With Images as files on, each picture is saved as images/image1.png and so on, and the download becomes a ZIP holding the .md beside its pictures.
It says my file is a legacy .doc. What does that mean?
A .docx is a ZIP package. A Word 97–2003 .doc is a different binary format, and its first eight bytes say so. The tool checks them as the file lands and reads nothing more. Open it in Word, Google Docs or LibreOffice, use Save As to make a .docx, and drop that instead.
Missing something in DOCX to Markdown? Suggest a feature →
Tell someone who needs this.