Limitations & Troubleshooting

Security & safety choices

• Raw HTML is disabled in Markdown input to reduce security risk.
• Remote image embedding is optional. When enabled, only HTTP(S) images are fetched and embedded into the DOCX.

Images

• Remote images (for example https://…/image.png) can be embedded when “Embed images from remote URLs” is enabled on the Convert page.
• Local file paths inside Markdown are ignored (for example ./images/logo.png).
• Very large images may be downscaled to fit within a Word-safe width so the document stays readable.

Diagrams and charts

md2docx can render fenced diagram blocks (Mermaid, Graphviz/DOT, PlantUML) and Chart.js configs into images embedded in the DOCX.

• If a renderer fails (or isn’t available in a self-hosted environment), md2docx falls back to including the fenced block as a formatted code block.
• Large diagrams may be scaled down to fit the page. Prefer splitting complex diagrams into smaller components.

For examples and best practices, see Embedding Mermaid diagrams and Diagrams beyond Mermaid.

Math

• Inline math: $E = mc^2$
• Block math: $$ E = mc^2 $$

Math is rendered into images for consistent DOCX output. If an equation doesn’t render, check for mismatched $ delimiters or characters that should be escaped. See Math and equations in Word for troubleshooting.

Templates

Templates control fonts, spacing, and Word styles. If something looks “off”, it’s usually a style mapping issue.

• Headings map to Word’s Heading 1–6 styles.
• Paragraphs map to Normal.
• Blockquotes map to a quote/callout style.

See Custom DOCX templates for a step-by-step setup guide.

When something fails

1. Try a smaller input to isolate the section causing the issue.
2. If you’re using remote images, disable the option and confirm the rest of the document converts.
3. For diagrams/charts, validate the fenced block syntax (for example JSON validity for ```chartjs).
4. If you can share a safe Markdown snippet, send it via the Contact page.