Markdown to Word

Why headings must be styles, not big text

If you paste Markdown into Word as it is, you keep looking at the hashes; if you paste it from some preview, headings become big bold text, which looks like a heading but is not one as far as Word is concerned. The difference shows up the moment you try to do anything serious: the automatic table of contents stays empty, the navigation pane shows no structure, levels cannot be collapsed and chapter numbering never starts. Here headings use Word's Heading 1, Heading 2 and Heading 3 styles, which is exactly what Word expects.

What gets converted

Headings from one to six hashes, bold, italic, strikethrough, inline code and code blocks fenced with triple backticks.

Bulleted and numbered lists, nested on several levels and mixed too; a numbered list that starts again from 1 really does start from 1, and one that starts at 5 starts at 5.

Tables with the header row in bold on a grey background, repeated at the top of every page, right aligned or centered if you said so with colons in the row of dashes.

Block quotes, horizontal rules, task lists with check boxes and clickable links (including bare web and email addresses written in the text).

Links to a section of the same text, like [see](#summary): the matching heading gets a Word bookmark, so in the .docx file the link really takes you there. If that heading is missing, the text stays plain and you get a warning, instead of a blue link that goes nowhere. In the clipboard copy those jumps stay plain text: an internal link lives inside the document, and the moment it leaves this page it has nowhere to jump to.

The document is A4 with 2 cm margins, Calibri 11 for the text and Consolas for code.

Copy to the clipboard or download the file

The orange button puts both the formatted version and the plain text on your clipboard: paste into Word online, Google Docs, an email or a message and it arrives already laid out, with no file in between. That is the fastest route when the text has to go inside a document that already exists. The .docx file is what you want when the document has to be delivered, attached or filed: it is an ordinary Word file, and it opens in Word, LibreOffice, Pages and Google Docs.

The table of contents updates on first open

If you tick «Add a table of contents», the document starts with a real table of contents field. It comes out empty, and it cannot be otherwise: page numbers depend on fonts and margins, so only the program that opens the file knows them. The first time you open it Word asks whether to update the fields: say yes and the table fills in by itself. If it does not ask, right click on the box and choose Update field, or go to the References tab and choose Update table.

What stays out, said up front

Images do not go into the document: Markdown only carries their address, and this page never downloads anything from the network, so the caption in square brackets takes their place. HTML written inside the Markdown, LaTeX maths, footnotes and reference style links like [1]: address are not interpreted. Tables inside tables do not exist in Markdown, so they do not exist here either. Code has to be fenced with triple backticks: code marked only with a four space indent stays plain text, and a line of three dashes is always a horizontal rule, never a heading. If a table has no row of dashes under the header it is not a table for anybody, us included: you get a warning instead of invented columns.

All in your browser, even offline

The Word document is built right here, byte by byte: a .docx file is a ZIP archive containing XML files, and this page writes both the XML and the ZIP. The text you paste never leaves your device, is never uploaded and is never stored: you can unplug the network and the page still works. That is the difference that matters when the text is a set of minutes, an expert report or a confidential review.