Guide · Word → Markdown
What survives when Word becomes Markdown
"Keep the formatting" means two different things, and which one you mean decides whether you'll like the result.
One of them survives: the outline. Headings, lists, tables, emphasis — the parts that say how the document is put together. The other one, the look of it, has nowhere to go, because Markdown is plain text and plain text has no fonts, colours, margins or page breaks. That's the format's ceiling, not a missing feature.
Structure survives, appearance doesn't
Open a .docx and every paragraph carries a style name alongside its formatting. The style name is the part with meaning — Heading 2, List Paragraph, Quote — and the formatting is only how Word chose to draw it today.
The converter reads the first and discards the second. A Heading 2 becomes ## — not text with a font size attached. Wherever the Markdown ends up, it picks up that project's own heading style.
Markdown has no syntax for a typeface or a margin, which means there is no version of this that keeps them. If you need the page to look identical, you want a PDF, not Markdown.
The # signs come from real heading styles
This is the one thing worth doing in Word before you convert, and it's the difference between good output and a wall of paragraphs.
A line you enlarged and bolded by hand is still a normal paragraph as far as the file is concerned, so it converts to a paragraph. No rule could turn 16pt-and-bold back into ## without also mangling every emphasised sentence in the document.
- 01In Word, click into one of your headings and glance at the Styles gallery. A highlighted Normal is the whole problem in one word.
- 02Pick Heading 1, 2 or 3 from that gallery. The look will change — edit the style's definition if the new look bothers you, rather than going back to sizing by hand.
- 03Do the same for lists — use the list buttons rather than typing "1." and a tab. Hand-typed numbers convert to literal text that no longer renumbers.
- 04Convert, then scan the output for # and -. A file with no # in it was never structured to begin with.
What comes through
Heading levels one through six, from Word's styles. Word's Title and Subtitle styles map to # and ## as well, since that's what they mean.
Bold as **, italic as _, strikethrough as ~~. Superscript and subscript stay as <sup> and <sub> — Markdown has no syntax for them and dropping them would change what a formula or a footnote marker says.
Links, ordered and unordered lists at any nesting depth, blockquotes from the Quote and Intense Quote styles, and paragraphs styled Code or Preformatted as fenced code blocks.
A nested bulleted list,
and a numbered list starting at 3- Outer
- Inner
- Second
3. Third
4. FourthWhat gets dropped, and why
Fonts, sizes, colours, highlighting, alignment, indentation, line spacing, page breaks, headers, footers and margins. All of it is presentation belonging to a page, and Markdown isn't a page.
Underline is the drop most likely to surprise you. Markdown has no underline, and the nearest thing — a link — would be worse than nothing, so underlined text comes out as plain text.
Track changes and comments go: you get the final text, not the editing history. Text boxes, SmartArt and charts don't survive either, only their text if they hold any. Word will also tell the converter about styles it couldn't map; those notes appear above the output, deduplicated and capped at eight, with a line saying how many more there were.
Tables come through, merges don't
Tables become standard pipe tables. Pipes inside cell text are escaped as \| so a cell containing a pipe doesn't split the row in two, and rows shorter than the widest row are padded out so the table stays rectangular.
Merged cells are the exception, and it's a hard one: Markdown has no colspan or rowspan. A cell merged across two columns keeps its text and leaves an empty cell beside it. If the merges carry meaning, unmerge them in Word first — often they were only there to centre a title.
Cells hold inline formatting fine — bold, italic, code, links. Block content inside a cell does not survive as blocks: a bulleted list in a cell comes out as its items run together, because a pipe table row is one line.
Header cell merged across two columns| Merged head | |
| --- | --- |
| 1 | 2 |Images, and the one thing .doc can't give you
Old .doc files are the exception. That format is pre-2007 binary, read here byte by byte in your browser, and images can't be recovered from it at all — nor can exact list numbering. Text, headings, tables, bold and italic do come through, and the output says it took that route so you're not left guessing. If Word is handy, a Save As .docx gives a cleaner result.
One more thing worth knowing: Word hyperlinks often carry tracking parameters, and documents saved out of Google Docs wrap their links in a google.com/url redirect. Both are unwound to the real destination, and the output says so — changing where a link points is worth being told about.
- 01Inline base64 embeds every image in the Markdown itself. One self-contained file, no missing pictures — but a data URI is about a third larger than the image was, and it makes the file unpleasant to read in a text editor.
- 02Keep a slot writes  and leaves the file to you. Use this when the Markdown is going into a repo that already has an images folder. The name is built from the alt text, lowercased and hyphenated.
- 03Drop them removes images entirely. Right for a text-only export, wrong if you'll wonder later what was there.
Fix the heading styles, then drop the file in. Nothing is uploaded — the .docx is unzipped in this tab — so an unreleased draft is a fine thing to test with.
Word → MD