Markdown Export Tips (2026) – How to Get Better Word and PDF Output

If your Markdown looks good in preview but falls apart in Word or PDF, the problem is usually not one single feature. It is usually a combination of:

• unstable images
• weak heading structure
• overly complex list/code nesting
• renderer-specific extensions
• assumptions that preview and export behave the same way

The fastest path to better output is not “more formatting.” It is more predictable structure.

The Short Version

If you want safer Word/PDF export, do these first:

1. use one clear H1 and clean H2/H3 hierarchy
2. keep tables simple unless HTML is truly necessary
3. use stable image sources and explicit sizing when needed
4. keep code blocks and complex lists carefully indented
5. isolate Mermaid and math instead of mixing them into fragile structures
6. test one real export before sharing important documents

That is the practical baseline.

Start with Structure, Not Styling

Many export problems begin before images or tables ever show up.

Good export-friendly structure usually means:

# Quarterly Report
## Summary
## Findings
### Performance
### Risks
## Appendix

Why this matters:

1. Word/PDF outline quality improves
2. TOC generation becomes more predictable
3. section links are easier to maintain
4. the document reads like a real report instead of a visually hacked note

If a document uses headings mainly to make text “look bigger,” export quality usually gets worse, not better.

If you need the deeper version of this structural rule, read the Markdown Heading Guide. Clean headings do more for export quality than decorative formatting tricks, especially once a document gets long.

Images: Stable Sources Beat Clever Tricks

Images are one of the biggest export-risk categories.

The safest practices are:

1. use a stable public https:// URL or uploaded asset
2. avoid relying on local absolute file paths in browser workflows
3. use explicit size control when layout matters
4. crop screenshots before export instead of dumping giant captures

Why this matters in md2word:

1. remote images are pre-downloaded before export
2. local absolute paths are not a reliable web-export strategy
3. many images or many remote images increase conversion complexity

When those assumptions fail, the result is not always a subtle degradation. In the current pipeline, blocked local paths and failed remote downloads can trigger placeholder fallback behavior. That is why image review belongs in your export checklist, not just in the drafting phase.

If an image is important to the document, treat it like content infrastructure, not decoration.

For deeper image-specific guidance, read the full Markdown Images Guide.

Tables: Keep Them Readable, Not Just Technically Valid

A Markdown table can be syntactically valid and still export badly.

High-risk table patterns:

1. too many columns
2. giant text blocks inside cells
3. mixed links, images, and code all inside the same row
4. trying to force layout tricks that plain Markdown tables do not support

Safer pattern:

1. reduce the table to essential columns
2. keep one concept per column
3. move commentary outside the table
4. switch to HTML table only when you truly need advanced structure

If a table already feels cramped in the browser, it will usually feel worse in Word/PDF.

For deeper table guidance, read the Markdown Table Guide.

Code Blocks and Lists Need Discipline

Code blocks and lists are individually stable, but the combination is fragile when indentation drifts.

Safer pattern:

1. Install dependencies

   ```bash
   pnpm install
   pnpm test
   ```

Riskier pattern:

1. Install dependencies
```bash
pnpm install
```

What goes wrong:

1. the code block may fall out of the list
2. spacing changes after export
3. hierarchy becomes visually confusing

If the document mixes lists, code blocks, screenshots, and long explanations in one place, check the indentation before you blame the exporter.

For deeper guidance, read the Markdown Code Block Guide and Markdown List Guide.

Mermaid, Math, and HTML Are Powerful but Not “Free”

These features add value, but they are not as portable as plain headings, paragraphs, and lists.

Mermaid

In md2word, Mermaid diagrams are rendered into images before export. That means Mermaid can work well, but it also means:

1. rendering depends on the diagram pipeline being available
2. width control is more stable when declared clearly
3. Mermaid should stay in dedicated code fences, not be mixed into other fragile structures

If the render chain fails, do not assume the final file will keep an equivalent visual result. Read the full Markdown Mermaid Guide before you design a document that depends heavily on exported diagrams.

Math

Display math and LaTeX-style notation often need normalization before export. If formulas matter, keep them isolated and readable rather than hiding them inside dense paragraphs.

Preview rendering is not the same guarantee as export fidelity. If equations are central to the document, read the full Markdown LaTeX Guide and standardize your delimiter choice before the file gets harder to maintain.

If you also rely on footnotes or quote-style callouts, keep those structures simple too. Dense citation-heavy notes and nested admonition-like blocks are common places where preview and export start to drift apart.

Raw HTML

Raw HTML can be useful, especially for image sizing and some table structures. But HTML support is not a universal export guarantee. A renderer may accept HTML in preview and still treat it differently downstream.

Use HTML deliberately, not as a default escape hatch for every formatting problem.

Do Not Confuse “Preview Looks Fine” with “Export Is Safe”

This is one of the most expensive assumptions in Markdown workflows.

Preview and export may differ because:

1. heading IDs are generated differently
2. image paths resolve differently
3. HTML support differs
4. Mermaid/math handling differs
5. layout constraints in Word/PDF are much tighter than in a browser pane

If the document is important, preview is only the first check. Final export is the real check.

What Makes a Document Heavy or Fragile

In the current md2word pipeline, complexity rises when a document combines:

1. many images
2. many remote resources
3. Mermaid diagrams
4. display math
5. heavy HTML usage
6. very long lines or paragraphs

That does not mean “do not use these features.” It means:

the more of them you combine in one file, the more carefully you should test the final output.

Pre-Export Checklist

Before exporting an important document, check these:

1. headings follow a clean hierarchy
2. section names are final enough that anchors will not move unexpectedly
3. images are uploaded or point to stable URLs
4. tables are not wider than the target page can realistically support
5. list/code indentation is consistent
6. Mermaid and math are isolated in their own blocks
7. no critical content depends on renderer-specific HTML quirks
8. at least one real DOCX or PDF export has been reviewed

FAQ

What usually breaks export first?

Images, overly complex tables, and list-plus-code indentation issues are among the most common early problems.

Is plain Markdown always safer than HTML?

Usually, but not always. For some cases like explicit image sizing, a small amount of deliberate HTML can be safer than vague Markdown assumptions.

Should I avoid Mermaid and math entirely?

No. Just isolate them, keep them intentional, and test final export instead of assuming preview parity.

Why does one document export fine while another similar one struggles?

The second one often has a higher combined complexity: more remote assets, more HTML, more diagrams, more long paragraphs, or more nested structures.

What is the best general rule?

Prefer simple, structural, explicit Markdown over clever formatting tricks.

Further Reading

• CommonMark Spec
• Pandoc Manual: Images
• Pandoc Manual: Headings and sections
• Pandoc Manual: Tables
• Pandoc Manual: Raw HTML

Changelog

• 2026-03-18: Initial high-value release with verified guidance on export-safe structure, image strategy, table risk, code/list stability, Mermaid/math boundaries, and a practical pre-export checklist.
• 2026-03-19: Added stronger md2word-specific notes on heading strategy, image placeholder fallback, and Mermaid/LaTeX failure modes.

Next steps: Explore Markdown Mermaid Guide, Markdown LaTeX Guide, Markdown Footnote Guide, Markdown Quote Guide, Markdown Images Guide, Markdown Heading Guide, Markdown Code Block Guide, Markdown List Guide, and Markdown Hyperlink.