@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

npm install @m2d/image

pnpm add @m2d/image

yarn 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

import { imagePlugin } from "@m2d/image";

const plugins = [
  htmlPlugin(), // Optional — parses HTML <img> into image nodes
  mermaidPlugin(), // Optional — emits image/svg nodes for diagrams
  imagePlugin(), // ✅ Must come after HTML/Mermaid plugins
  tablePlugin(),
];

🧠 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

IImagePluginOptions {
  /** Scale factor for base64 (data URL) images. @default 3 */
  scale?: number;

  /** Fallback format to convert unsupported image types. @default "png" */
  fallbackImageType?: "png" | "jpg" | "bmp" | "gif";

  /** Image resolution function used to convert URL/base64/SVG to image options */
  imageResolver?: ImageResolver;

  /** Max image width (in inches) for inserted image */
  maxW?: number;

  /** Max image height (in inches) for inserted image */
  maxH?: number;

  /** Optional placeholder image (base64 or URL) used on errors */
  placeholder?: string;

  /** Enable IndexedDB-based caching. @default true */
  idb?: boolean;

  /**
   * Optional salt string used to differentiate cache keys for similar images (e.g., dark/light theme).
   */
  salt?: string;

  /** Duration in minutes after which cached records are removed as stale. Default: 7 days (10080 minutes). */
  maxAgeMinutes?: number;

  /**
   * Applies generic fixes to known SVG rendering issues (e.g., Mermaid pie chart title alignment).
   * Designed to be overridden to handle tool-specific quirks in generated SVGs.
   *
   * @param svg - Raw SVG string to transform.
   * @param metadata - Optional metadata such as diagram type or render info.
   * @returns Modified SVG string.
   */
  fixGeneratedSvg?: (svg: string, metadata: any) => string;
}

imageResolver

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

imagePlugin({
  imageResolver: async (src, options, node) => {
    const response = await fetch(src);
    const arrayBuffer = await response.arrayBuffer();
    return {
      type: "png",
      data: arrayBuffer,
      transformation: {
        width: 400,
        height: 300,
      },
    };
  },
});

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