Md2DocxError Handling & Diagram Fallbacks
Updated 5 min ago
Strategies for handling broken images, remote fetch errors, and failed diagrams.
@m2d/image provides a comprehensive error-handling system designed to ensure documents generate reliably even when remote images fail to load or complex diagrams cannot be rendered.
Error Modes (errorMode)
The errorMode option governs the general response when an image source fails to resolve (network timeout, invalid URL, decode error):
| Mode | Behavior | Use Case |
|---|---|---|
"warn" (default) | Emits a styled, muted text badge in Word: [Image: alt text] or [Image unavailable]. | Interactive authoring and user-facing exports where silent omissions are confusing. |
"silent" | Completely removes the image node from the Word document (0 XML overhead, 0 relationships). | Clean production pipelines where broken images should simply be omitted. |
"throw" | Rejects the toDocx conversion promise with the underlying Error. | Automated CI/CD test suites requiring 100% asset integrity before publishing. |
"placeholder" | Inserts a custom image provided in options.placeholder. If omitted, falls back to a warning badge. | Branded templates with an official fallback placeholder graphic. |
import { imagePlugin } from "@m2d/image";
const plugin = imagePlugin({
errorMode: "warn",
placeholder: "https://example.com/assets/placeholder.png",
});Mermaid Diagram Fallbacks (mermaidFallback)
When diagram plugins like @m2d/mermaid fail to render a diagram (e.g. invalid syntax or unrecoverable tokens), @m2d/image detects the preserved data.mermaid source and applies the mermaidFallback policy:
"code"(default): Converts the failed diagram into an authentic Word code block (lang: "mermaid"), complete with native borders, block styling, and Consolas monospace font."warn": Emits a styled warning text badge:⚠️ [Mermaid Diagram Error: ...]."silent": Drops the diagram completely from the document.
Collapsible Headings (collapsibleHeading)
To prevent error fallback code blocks from cluttering the document flow, @m2d/image prepends an H6 heading above the fallback code block:
###### ⚠️ Mermaid Diagram Source (Render Fallback)In Word desktop and Microsoft 365:
depth: 6maps to Word's Heading 5 style whenuseTitle: true.- This creates a natively collapsible section directly in Word desktop.
- Because Word's default Table of Contents only indexes levels 1–3 (
{ TOC \o "1-3" }), the error notice never pollutes your document's Table of Contents.
To customize or disable the heading:
imagePlugin({
// Disable the heading (renders only the code block)
collapsibleHeading: false,
// Or customize the heading text
collapsibleHeading: "⚠️ Custom Fallback Notice",
});SVG Fallbacks (svgFallback)
For non-Mermaid SVGs that cannot be rasterized:
"warn"(default): Emits a muted text badge:[Image: {alt || "SVG unavailable"}]."code": Renders the raw SVG XML markup in a standard Word code block (lang: "xml")."silent": Completely omits the node.