Markdown to Word Formatting Problems: 7 Common Issues and How to Fix Them

Markdown to Word conversion is supposed to be a solved problem — until your table arrives as a wall of pipe characters or your flowchart shows up as source code. Here are the seven failures we see most often, what causes each one, and the fix.

1. Tables arrive as pipe characters

Symptom: instead of a table, the Word doc shows | Name | Value | as literal text.

Cause: either the converter doesn't support GFM tables, or the table syntax is subtly broken — most often a missing separator row (| --- | --- |) or inconsistent column counts between rows.

Fix: validate the table renders in a preview first. Every row needs the same number of | separators, and the second line must be the dash separator row:

| Name  | Value |
| ----- | ----- |
| Alpha | 10    |

If the syntax is right and it still fails, the tool is the problem — use a converter with full GFM support.

2. Mermaid diagrams appear as code, not diagrams

Symptom: the .docx contains the literal text flowchart LR ... in a code box.

Cause: the converter doesn't render Mermaid. Most don't — Pandoc needs the mermaid-filter plugin plus Node.js; the majority of online tools just pass the code block through.

Fix: two options. Render diagrams manually to PNG (via the Mermaid Live Editor) and embed them as images — tedious but universal. Or use a converter that renders Mermaid natively into the .docx. Also check your diagram syntax first: one invalid arrow makes even a capable renderer fall back to code.

3. Math formulas show as raw LaTeX

Symptom: $$\frac{a}{b}$$ appears as-is in the document.

Cause: math support is the most commonly skipped feature in Markdown converters, and Pandoc's math handling depends on output settings.

Fix: confirm your delimiters are standard ($...$ inline, $$...$$ block — Obsidian-style is fine), then use a converter with LaTeX/KaTeX support. If a specific formula fails while others work, test it in isolation — a single unsupported macro can break the block.

4. Images are missing from the output

Symptom: empty spaces or broken-image icons where pictures should be.

Cause: the Markdown references images by local relative path (![](images/chart.png)). A browser-based tool cannot read files from your disk, and even Pandoc fails if you run it from the wrong directory.

Fix: use absolute https:// URLs for images when possible. For local-only images (e.g., a Notion export), convert the text first and drag the images into Word afterward, or upload the images and swap in the URLs. Details in our Notion export guide.

5. Code blocks lose highlighting (or keep their backticks)

Symptom: code arrives as plain body text, sometimes with \``` still visible.

Cause: visible backticks mean the fence wasn't parsed — usually a missing blank line before the fence or unclosed triple backticks earlier in the document (everything after an unclosed fence is treated as code). Plain unstyled code means the converter ignores the language tag.

Fix: ensure every fence opens and closes, add the language identifier (\``python`), and keep a blank line before the opening fence. Then use a converter that applies syntax-aware styling.

6. Nested lists flatten or renumber

Symptom: sub-items lose their indentation, or an ordered list restarts at 1 mid-way.

Cause: inconsistent indentation in the source — Markdown needs nested items indented by a consistent 2 or 4 spaces, and mixing tabs with spaces confuses parsers. A paragraph inserted between list items also splits the list, restarting numbering.

Fix: normalize indentation (pick 4 spaces per level and stick to it), and indent continuation paragraphs to the level of the item they belong to. VS Code's "Convert Indentation to Spaces" command fixes the tab/space mix in one step.

7. Chinese, Japanese, or Korean text renders with the wrong font

Symptom: CJK characters in the .docx fall back to a mismatched or boxy font, or bold CJK text doesn't look bold.

Cause: the converter writes a Latin font name (e.g., Calibri) into the document without an East Asian font mapping, so Word substitutes something arbitrary.

Fix: use a converter that sets proper CJK font pairs, or fix it post-hoc in Word by selecting all and setting the East Asian font explicitly. We wrote a dedicated deep-dive: fixing Chinese fonts in Markdown to Word conversion.

The 30-second diagnostic

When a conversion looks wrong, check in this order:

1. Preview the Markdown in any renderer (VS Code preview, or the converter's live preview). If it looks wrong there too → your Markdown syntax is the issue.
2. If the preview is right but Word is wrong → the converter dropped the feature. Switch tools for that document type.
3. If only one section fails → isolate it. A single unclosed code fence or malformed table row can corrupt everything after it.

Most "converter bugs" turn out to be case 1 — and most real converter gaps are Mermaid, math, and CJK fonts, which is exactly why we built those three into this tool.