Word to Markdown Formatting Guide: Preserve Every Style

Formatting is where most Word-to-Markdown conversions go wrong. Bold text shows up as plain text. Tables collapse. Headings turn into unstyled paragraphs. This guide explains exactly what happens during Word to Markdown conversion and how to control the output.

Understanding the Conversion Pipeline

When you convert a Word document to Markdown, two things happen:

1. DOCX → HTML — mammoth.js parses the Word XML and maps each element to HTML
2. HTML → Markdown — turndown converts the HTML to Markdown syntax

The second step is lossless if the HTML is clean. The first step is where formatting complexity matters — Word’s styles need to map to known HTML equivalents.

Use WordToMD’s converter to see exactly how your document converts in real time.

Heading Styles

The most important formatting decision in Word is using built-in heading styles.

Common mistake: Manually formatting text as large and bold instead of applying a Heading style. This looks like a heading in Word but converts to bold text in Markdown, not ##.

For the complete headings reference, see Markdown Headings Guide.

Text Emphasis

Underline and highlight have no Markdown equivalent in standard syntax. After conversion, use HTML <u> tags or custom CSS classes if your publishing platform supports them.

Lists

Word’s automatic list formatting converts cleanly:

- Bullet item one
- Bullet item two
  - Nested bullet (indent 2 spaces)

1. First item
2. Second item
   1. Nested numbered item

What breaks lists: Manually typed dashes or numbers that aren’t actual Word list items. These look like lists visually but Word treats them as plain text paragraphs. The fix: select them in Word and apply the List Bullet or List Number style.

Tables

Standard tables convert to GitHub Flavored Markdown table syntax:

| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Cell A | Cell B | Cell C |
| Cell D | Cell E | Cell F |

What breaks tables:

• Merged cells — the cell spanning multiple columns or rows will be collapsed
• Multi-line cell content — line breaks inside cells are stripped
• Nested tables — inner table is flattened to plain text

For a complete breakdown, see Markdown Tables: A Complete Guide.

Code and Preformatted Text

Text formatted with a monospace font (Courier New, Consolas) in Word maps to inline code:

Use `console.log()` to debug.

For fenced code blocks with syntax highlighting, apply Word’s “Code” paragraph style if your template has one, or add the triple backtick fencing manually after conversion. See Markdown Code Blocks Guide for the full syntax.

Hyperlinks

Word hyperlinks convert perfectly:

Visit [WordToMD](https://wordtomd.org) for instant conversion.

The link text and URL are both preserved. Bookmarks (internal links within the same document) may not convert if the target doesn’t exist in Markdown.

Images

Images are where Word-to-Markdown conversion consistently falls short. mammoth.js can extract embedded images as base64 data URIs, but the default behavior is to note their presence in Conversion Notes. After conversion:

1. Export images from Word: File → Save As → Web Page (HTML)
2. Reference them in Markdown: ![Alt text](path/to/image.png)

Special Characters and Symbols

Word often inserts special Unicode characters automatically:

• Smart quotes ("...") → preserved as Unicode characters
• Em dash (—) → preserved
• Non-breaking spaces → converted to regular spaces
• Copyright symbol (©) → preserved

If you need ASCII-only output, do a find-and-replace in your text editor after conversion.

Custom Word Styles

If your Word document uses custom paragraph styles (like “Callout” or “Warning”), mammoth.js logs them as conversion notes. You’ll see messages like “Unrecognised paragraph style: Callout.” WordToMD filters out these informational messages by default.

To handle custom styles, you’d need a local Pandoc setup with a custom filter — see Pandoc Word to Markdown for that approach.

Formatting Checklist Before You Convert

Apply this checklist to your Word document before converting:

• All headings use Word’s built-in Heading 1/2/3 styles (not manual formatting)
• Lists are created with Word’s list tools (not typed dashes/numbers)
• Tables are simple grids (no merged cells)
• Code uses a monospace font
• Hyperlinks are real hyperlinks (not just blue underlined text)

FAQ

Why are my headings converting as bold text? You applied manual bold + font size formatting instead of the Heading style. In Word, click on the paragraph and look at the Styles panel — it should say “Heading 1” not “Normal.”

My numbered list restarted at 1 in the wrong place — how do I fix it? Set list continuation in Word: right-click the list → Continue Numbering. Or edit the Markdown directly after conversion.

The table alignment looks wrong in Markdown. What happened? GFM tables use |---| for alignment separators. WordToMD generates these automatically. If rendering looks off, check that no cells have pipe characters (|) in their content — escape them as \|.

Conclusion

Getting clean Word to Markdown formatting is mostly about using Word correctly. Apply built-in heading styles, use Word’s list and table tools, and you’ll get near-perfect output from the WordToMD converter. For edge cases — custom styles, complex tables, images — the tips above will get you the rest of the way there.