AnymarkHow to convert a Word document to Markdown (three ways, and what each loses)
A Word document and a Markdown file describe the same things, headings, paragraphs, lists, tables, emphasis and links, in very different ways. Word stores formatting as styles and direct runs; Markdown stores structure as punctuation. Converting well means mapping the first onto the second without inventing structure that was never there. Here are the three ways people do it, with the trade-offs.
1. Pandoc on the command line
Pandoc is the reference tool, free and scriptable:
pandoc report.docx -t gfm -o report.md --extract-media=report_assets
What you get is faithful and predictable. Headings follow Word’s heading styles, lists keep their nesting, tables become pipe tables, pictures land in the folder you name. The limits are the ones Markdown itself has: text boxes, columns, footnote placement and tracked changes come out flattened or not at all, and a table with merged cells is written as a plain grid with the merged cell repeated or empty.
Pandoc is the right choice when you convert many files the same way and are comfortable with a terminal. It is the wrong choice for a one-off from someone who has never opened one.
2. Copy from Word, paste into a Markdown editor
Most Markdown editors convert rich text on paste. Select all in Word, paste into the editor, save. It works for short, simple documents and fails quietly on anything else: headings that were only made big and bold (not styled as headings) arrive as bold paragraphs, numbered lists arrive as text with literal numbers, and tables arrive as tab-separated lines or not at all. Pictures are usually dropped.
It is fine for a memo. Check every heading and list before trusting it.
3. Open the .docx in an app that converts on open
This is what Anymark does. You double-click the Word file, it is read on your computer, and what you see is the converted document, editable, with the original untouched on disk. Saving writes a .md beside it.
The engine reads the document’s own structure rather than its appearance: heading styles become # headings, list paragraphs become list items with their nesting, tables become pipe tables, and a table with merged cells is kept as an HTML table so nothing is lost. Pictures go to a folder beside the file (or inline, your choice). Old .doc files from Word 97 to 2003 and RTF are read by a built-in parser too, which Pandoc does not do.
What no converter can keep
Be suspicious of any tool that claims otherwise:
- Page layout. Columns, text boxes, exact margins and page breaks. Markdown has one column and no pages.
- Fonts and colours of the letterhead. Markdown has no fonts. (Anymark keeps text colour and highlight as the small inline HTML tags every reader understands, but a 14-point Garamond heading is just a heading.)
- Tracked changes and comments. Accept or reject them in Word first.
- Fields. A table of contents, cross-references and dates that update themselves become their last displayed text.
How to check a conversion in two minutes
- Count the headings in the original’s navigation pane and in the Markdown. The numbers should match.
- Look at the longest table. Are the column headers in the header row? Are numbers right-aligned where they should be?
- Search the Markdown for
**runs that are whole paragraphs; those were headings Word did not style as headings. Fix the style in Word and convert again, or promote them by hand. - Open the pictures folder. The count should match the figures you remember.
If those pass, the rest is almost always fine.