Convert Markdown to Word

What carries over

Lines that follow each other without a blank line between them join into one paragraph, as Markdown intends, so hard-wrapped text reads as flowing paragraphs in Word. Numbered lists count from 1 in Word, whatever numbers the Markdown used.

What to fix after opening

• Front matter. A block of settings between --- lines at the top of a file, used by static site generators and some note apps, comes in as dividers and ordinary text. Delete it in Documents.
• Underlined headings. A heading written with a line of === or --- under it is not read as a heading; use # marks, or pick the style in Documents.
• HTML inside Markdown shows as plain text, tags and all.
• Pictures. In Markdown a picture is a link to a separate file. Check each one, and add any that are missing with Insert picture.
• Footnotes and reference-style links stay as the plain text you typed.

Most READMEs, notes and docs open with nothing to fix. The checks above are for files written for a particular site or tool.

And the other way: Word to Markdown

Documents writes Markdown too. Open any .docx and choose Save a copy as Markdown (.md)… in the save menu. Headings get # marks, lists become - and 1., checklists - [ ] and - [x], tables become pipe tables with the first row as the header, and bold, italic, strikethrough and links are marked up. Page breaks and dividers become ---, and nested lists are indented by two spaces.

What Markdown has no way to say is left out: underline, colors, highlighting, fonts, sizes and alignment, and merged table cells are flattened. Pictures stored inside the Word file are not exported; a placeholder marks where each one was, so you know where to link the image file.

That makes Documents a handy bridge for documentation kept in a Git repository: a colleague's .docx becomes Markdown you can commit, and your Markdown becomes a .docx they can open.

Who converts Markdown to Word, and why

Markdown is how many developers, technical writers and note apps write: plain text that is easy to version and compare. Word is what clients, managers, publishers and universities often ask for. Converting bridges the two: a README turned into a handout, notes from a note-taking app turned into a report, documentation sent to a reviewer who works in Word. Links keep their targets, so a converted README still points to the same pages.

Plain text and web pages open the same way. A .txt file becomes one paragraph per line, and an .html file comes in without the page's scripts and styles. Either way the result is a new .docx, and the file you opened is left alone. Documents shows words and characters in its status bar; for more detail, such as reading time, the word counter in Text Studio does more.