Convert Word to Markdown

Convert a .docx Word document to clean Markdown in your browser. Headings, lists, tables and links come across. Nothing is uploaded anywhere.

🌐 Español

Drop your files here (.docx)

🔒 Private by design: your files are processed locally in your browser and never uploaded to any server.

Written and maintained by Last updated

Two libraries, one handoff

The conversion happens in two clean halves. First mammoth.js opens the .docx zip and rebuilds its semantic structure as minimal HTML: styled headings become real heading elements, bold and italic runs become strong and em, lists become nested ul and ol, hyperlinks get their targets resolved from the relationship part, and tables come out as plain rows and cells. None of Word’s presentation layer travels with it. Style definitions are consulted only to work out that a paragraph is a Heading 2 and are never emitted, section properties produce nothing, and the empty bookmark anchors Word scatters behind a table of contents are gone by the time the Markdown is written. That is the whole “no Office cruft” story, and most of it happens before Markdown is even involved.

Then turndown rewrites that HTML as Markdown, configured here for ATX headings, fenced code blocks, dash bullets and single-asterisk italics. A heading arrives as ## Section Two, a bold run as **bold**, a nested bullet indented under its parent. Because the input to that second half is machine-generated and predictable, the output is unusually tidy compared to pasting Word text into a Markdown editor and cleaning up by hand.

Word tables get a header row whether they had one or not

This is the sharpest edge in the whole conversion, and it is not avoidable. Word only marks a header row when you tick “Repeat as header row”, and most documents never do, so the first stage usually emits an ordinary data cell for every cell in the table. A pipe table in GitHub-Flavored Markdown, meanwhile, is required to have a header row and a dashed separator underneath it. The custom table rules here therefore promote the first row of every table, count its cells, and write a matching separator line. A two-column table comes out as a | Name | Qty | line, a | --- | --- | line, then the body rows.

Two more table facts to plan for. Merged cells collapse into single ordinary cells, because Markdown has no colspan. And a cell holding two paragraphs is flattened onto one line, since a newline inside a pipe row would terminate it. If you need to hand-build something more deliberate afterwards, the Markdown Table Generator gives you a spreadsheet grid with per-column alignment.

Underline, highlight and font size have nowhere to land

Markdown deliberately records structure and not presentation, so the losses here are honest rather than accidental. Underline, highlight colour, text colour and font size are dropped by the first stage before Markdown is even reached. Superscript survives that stage as a sup element and is then dropped by the second, since there is no Markdown for it. Headers, footers, page numbers, text boxes and columns never existed in the extracted body to begin with.

Strikethrough is the exception that did need work: it comes through as ~~text~~ because a dedicated rule was added for it, without which the formatting would have silently disappeared and left bare text behind.

Convert a batch in four steps

  1. Drop your .docx files into the box above, or click Choose files to select them.
  2. Set Embedded images to keep the pictures inline or to strip them out.
  3. Click Convert Word to Markdown.
  4. Download each .md file, named after the document it came from.

A note on batches: the loop has no per-file recovery, so one unreadable document stops the whole run rather than skipping past it. An empty document is not an error, incidentally, it just produces an empty .md file.

Data URIs or a clean text file

The Embedded images choice is really a choice about where your pictures should live. Keeping them means every image is inlined as base64 inside the Markdown, which makes the file portable and self-contained but pushes its size well past the original .docx and produces lines thousands of characters long. Removing them gives you the clean, diffable, version-controllable text file that most documentation workflows actually want, and you can add the images back as normal relative paths once you know where they will be hosted.

Where the .md file goes next

Once the structure is out of Word, the rest is easy. Paste the result into the Markdown to HTML Converter to see how it will render, or hand the .md file to Convert Markdown to PDF for a styled, paginated document with a theme picker. If the destination is a repository, the README Generator will take your converted sections and build a proper README around them. And if you wanted tags rather than plain text all along, Convert Word to HTML stops one step earlier in this exact pipeline and hands you the HTML instead. More writing tools sit on the text tools hub.

Frequently asked questions

Which Markdown flavour does the output use?

ATX headings with hash marks, dashes for bullets, single asterisks for italic and double for bold, tilde pairs for strikethrough, and GitHub-Flavored pipe tables. Those are the conventions GitHub, Hugo, Jekyll, Astro and Obsidian all read without extra configuration. Nested bullets are indented four spaces per level.

My Word table had no header row. What does the .md file show?

The first row becomes the header anyway. A GitHub-Flavored pipe table is required to have a header row followed by a dashed separator line, so there is no valid way to emit a headerless one. If your first row is real data, expect it to render in bold at the top of the table and move a copy of it down manually.

What does the Embedded images option actually change?

On the default setting, Keep (embedded as data URIs), each picture becomes an image tag whose source is a long base64 string, so the .md file is self-contained but can balloon to several times the size of the original document. GitHub will not render data-URI images in a README even though VS Code and Obsidian will. Switching to Remove images drops them entirely, and a paragraph that contained nothing but a picture disappears with it.

A pipe character inside one of my cells used to break the table. Does it here?

No. Every cell is scanned before it is written and a literal pipe is escaped with a backslash, so it stays visible inside the cell instead of being read as a column separator. Cells are also flattened onto one line, because a real newline inside a pipe table would end the row early. A two-paragraph Word cell therefore arrives as one run-on sentence.

Are footnotes and superscript preserved?

Footnotes are, superscript is not. Footnote markers become bracketed anchor links and the note texts land as a numbered list at the end of the file, each with a return arrow. Superscript has no Markdown syntax at all, so an exponent or an ordinal marker loses its raised position and the characters simply join the surrounding text.

Is the generated Markdown safe to paste into a site that renders raw HTML?

Read it first if the source document was not yours. Markdown-only special characters such as asterisks and underscores are escaped so they stay literal, but angle brackets are not, so a Word document whose visible text contains something shaped like an HTML tag will carry that text into the .md file unescaped. Most renderers will then treat it as markup. This does not apply to the document's formatting, only to text a person typed to look like a tag.

Related tools