When a Word file needs to become plain text with structure
Documentation often starts life in Word: a spec written by a product manager, a policy drafted by legal, a manual handed over by a client. The destination, though, is frequently a Git repository, a static site generator, a wiki, a knowledge base or a note-taking app, all of which speak Markdown. Copying and pasting loses the headings and lists, and retyping a 20-page document by hand takes hours.
Markdown is also a good archival and review format. It diffs cleanly in version control, so after converting a contract or a requirements document you can track every later change line by line, something a binary .docx file does not allow.
How the conversion works
A .docx file is a ZIP archive of XML files. The converter opens it in your browser, reads the document body and maps Word's structure to HTML first, then turns that HTML into Markdown. The two steps use the same Markdown rules as the site's HTML to Markdown converter, so output from both tools looks consistent.
What carries over, and how it is written:
- Headings become
#to######, one level per Word heading level from 1 to 6. - Bold becomes
**text**and italic becomes_text_. - Bulleted and numbered lists become
-and1.lists, with nesting preserved up to five levels deep. - Hyperlinks become
[text](url), including links to external sites. - Tables become pipe tables, with the first row used as the header.
- Footnotes and endnotes are collected into a numbered list at the end of the document, and each reference in the text becomes a link to its note.
The output is cleaned up so there is never more than one blank line between blocks.
Why headings sometimes come out as plain text
The converter recognises a heading by its paragraph style, not by how it looks. A line formatted with the built-in Heading 1 to Heading 6 styles becomes a Markdown heading. A line that the author made large and bold by hand is, as far as the file is concerned, an ordinary paragraph with bold text, and it comes out as **Introduction** rather than ## Introduction.
The same goes for the document title. Word's Title style is not a heading style, so a title set with it becomes a normal paragraph. If the structure matters, fix it in Word before converting: select the line and apply Heading 1 or Heading 2 from the Styles gallery. A quick way to check the document is the Navigation Pane in Word, which lists only real headings. Anything missing there will be missing from the Markdown outline too.
What is left out
Markdown is deliberately simple, so a lot of Word's layout has no counterpart:
- Images are not included, and a notice tells you how many were skipped. Embedding them as base64 text would make the file many times larger than the text itself.
- Underline, font, size and colour are dropped. Markdown has no syntax for them.
- Strikethrough text is kept, but without the strike marks.
- Headers, footers, page numbers and section breaks belong to the page layout, not the content, and are not converted.
- Text boxes and shapes may be lost or appear out of place, because they float outside the main text flow.
- Table cell formatting is flattened to plain text. Bold, links or lists inside a cell lose their formatting, and the paragraphs of a multi-paragraph cell are merged into one line, sometimes without a space between them.
A practical clean-up routine
The Markdown is usually 90 percent ready. A short pass fixes the rest:
- Scan the headings. Make sure there is one top-level
#heading if your site expects it, and that levels do not skip from#straight to###. - Check numbered lists that were interrupted by a paragraph or an image. Markdown may restart the numbering at 1.
- Look at tables with merged cells, which come through as rows with a different number of columns, and even them out by hand.
- Re-add images by exporting them from Word, placing the files next to the .md file and inserting
where they belong. - Preview the result with Markdown to HTML before publishing.
Files up to 50 MB are accepted, and the old binary .doc format is not. The document is read only in your browser tab, so confidential drafts never reach a server.