@m2d/image

Converts Markdown (![alt](url)), HTML <img>, and custom image/svg nodes into DOCX-compatible ImageRun elements.

Parsing HTML or Mermaid to SVG or image tags requires @m2d/html or @m2d/mermaid, respectively.
However, @m2d/image handles all image rendering to DOCX regardless of origin.

---

📦 Installation

1npm install @m2d/image

1pnpm add @m2d/image

1yarn add @m2d/image

---

🚀 Overview

The @m2d/image plugin for mdast2docx renders image nodes in DOCX output.

It supports:

• Markdown image syntax: ![alt](url)
• Images parsed from HTML via @m2d/html
• Images or SVGs emitted by plugins like @m2d/mermaid
• Base64 and external URLs
• Fallback handling
• Automatic caching

---

🛠️ Usage

1import { imagePlugin } from "@m2d/image";
2
3const plugins = [
4  htmlPlugin(), // Optional — parses HTML <img> into image nodes
5  mermaidPlugin(), // Optional — emits image/svg nodes for diagrams
6  imagePlugin(), // ✅ Must come after HTML/Mermaid plugins
7  tablePlugin(),
8];

🧠 If using @m2d/html or @m2d/mermaid, place them before this plugin. They generate image or svg nodes, but only @m2d/image renders them to DOCX.

---

🧪 Production Ready

This plugin is production-grade, supporting all major image scenarios:

• Remote images (CORS-safe)
• Data URIs and base64
• SVG-to-PNG fallback
• Image resolution caching (memory + IndexedDB)
• Partial style propagation via data-* attributes from HTML

💬 We welcome feedback, bugs, and contributions — open an issue or PR anytime.

---

⚙️ Plugin Options

1IImagePluginOptions {
2  /** Scale factor for base64 (data URL) images. @default 3 */
3  scale?: number;
4
5  /** Fallback format to convert unsupported image types. @default "png" */
6  fallbackImageType?: "png" | "jpg" | "bmp" | "gif";
7
8  /** Image resolution function used to convert URL/base64/SVG to image options */
9  imageResolver?: ImageResolver;
10
11  /** Max image width (in inches) for inserted image */
12  maxW?: number;
13
14  /** Max image height (in inches) for inserted image */
15  maxH?: number;
16
17  /** Optional placeholder image (base64 or URL) used on errors */
18  placeholder?: string;
19
20  /** Enable IndexedDB-based caching. @default true */
21  idb?: boolean;
22
23  /**
24   * Optional salt string used to differentiate cache keys for similar images (e.g., dark/light theme).
25   */
26  salt?: string;
27
28  /** Duration in minutes after which cached records are removed as stale. Default: 7 days (10080 minutes). */
29  maxAgeMinutes?: number;
30
31  /**
32   * Applies generic fixes to known SVG rendering issues (e.g., Mermaid pie chart title alignment).
33   * Designed to be overridden to handle tool-specific quirks in generated SVGs.
34   *
35   * @param svg - Raw SVG string to transform.
36   * @param metadata - Optional metadata such as diagram type or render info.
37   * @returns Modified SVG string.
38   */
39  fixGeneratedSvg?: (svg: string, metadata: any) => string;
40}

imageResolver

A custom function to fetch or transform the image. Receives the full image or svg node.

1imagePlugin({
2  imageResolver: async (src, options, node) => {
3    const response = await fetch(src);
4    const arrayBuffer = await response.arrayBuffer();
5    return {
6      type: "png",
7      data: arrayBuffer,
8      transformation: {
9        width: 400,
10        height: 300,
11      },
12    };
13  },
14});

You don’t need to implement caching — it’s handled internally with persistent storage. And it is configurable!

---

placeholder

Used if the image fails to load or decode. Can be:

• A base64/data URL string
• An url to placeholder image

---

idb

Whether to enable IndexedDB caching (in addition to in-memory).

• true (default): uses IndexedDB
• false: disables persistent cache

---

🧠 How It Works

1. Walks the MDAST tree for image and svg nodes
2. Resolves the image via default or custom imageResolver
3. Converts to a docx.ImageRun, including alt text and limited styles
4. Caches results keyed on the full node and options
5. Falls back if resolution fails

---

💡 Features

• Markdown images: ![alt](url)
• HTML <img>, <svg> support via @m2d/html
• Mermaid support via @m2d/mermaid or custom plugins
• Cross-environment caching (memory + IndexedDB)
• Alt text + basic style support from HTML via data-*

---

⚠️ Limitations

• Requires client-side (DOM) environment (uses <canvas>, <img>, etc.)
• Not compatible with server-side rendering (SSR) Node.js image plugin coming soon!
• External images must be accessible (CORS-safe URLs)
• Only a subset of styles are supported
• object-fit, fitWidth, and complex layout constraints are not supported
• Broken images are replaced with placeholder if defined; otherwise skipped

---

🔌 Related Plugins/Packages

Plugin	Purpose
@m2d/core	Converts extended MDAST to DOCX
@m2d/html	Parses raw HTML to extended MDAST
@m2d/mermaid	Adds mermaid diagrams as SVG/image nodes
@m2d/table	Renders table nodes to DOCX
@m2d/list	Enhanced list support (tasks, bullets)

---

⭐ Support Us

If you find this useful:

• ⭐ Star mdast2docx on GitHub
• ❤️ Consider sponsoring

---

🧾 License

MIT © Mayank Chaudhari

---

Made with 💖 by Mayank Kumar Chaudhari