DOCX to Markdown

Markdown is plain text, so it works with version control: every change shows up clearly in a diff, several people can work on it through pull requests, and it never becomes a binary file only one program can open. It is also what most documentation tools, wikis and static-site generators expect. Converting the first draft from Word saves the tedious part — re-creating every heading, list and table by hand — and lets you continue in the editor and workflow your team already uses.

The converter first reads the structure of the Word document, then writes that structure as Markdown. Formatting that Markdown cannot express is dropped instead of being turned into messy HTML.

Markdown refers to images by their path, and a Word document has no paths to offer. With Placeholders, each picture becomes an image line pointing to image-1, image-2 and so on, keeping its alternative text; save the pictures from Word, put them next to your Markdown file and replace the placeholders with their real names. Embed writes each picture into the Markdown as a data URI, which works in many previewers and keeps everything in one file, but makes the file long. Leave out removes images entirely, which is useful when you only need the text.

Simple tables convert cleanly to GitHub-style pipe tables, with the first row as the header. Markdown tables cannot merge cells, hold several paragraphs or lists in one cell, or have no header row, so cells that span several columns are written once, and paragraphs inside a cell are joined with line breaks. For complex tables, check the result, or keep that part as HTML, which most Markdown processors accept.

The document is unpacked and converted on your device with the open-source libraries mammoth and turndown, so confidential drafts never leave your computer. Files are checked by content: an old Word 97–2003 .doc file, an Excel workbook or a renamed file gets a clear explanation. Only .docx files are supported; save an old .doc as .docx first. Footnotes, comments, headers and footers are not part of the result. To go the other way use Markdown to DOCX, and for HTML instead of Markdown use DOCX to HTML.