Overview

$ pnpm add @m2d/image-node @m2d/core docx sharp

$ npm install @m2d/image-node @m2d/core docx sharp

import { toDocx } from "@m2d/core";
import { nodeImagePlugin } from "@m2d/image-node";
import { mermaidNodePlugin } from "@m2d/mermaid-node";
import remarkParse from "remark-parse";
import { unified } from "unified";

const markdown = `
# Server Generated Document

![Local Image](./images/architecture.png)
![Remote Logo](https://example.com/logo.png)

\`\`\`mermaid
graph TD
  Start[Start Process] --> Finish[Complete]
\`\`\`
`;

const mdast = unified().use(remarkParse).parse(markdown);

const docxBuffer = await toDocx(
  mdast,
  { title: "Server Document" },
  {
    plugins: [
      mermaidNodePlugin(), // Generates SVG AST nodes
      nodeImagePlugin({    // Rasterizes SVGs and resolves local/remote images
        pathPrefix: "./public",
        fallbackImageType: "png",
        maxW: 6.5,
        maxH: 9,
      }),
    ],
  },
  "buffer",
);

export interface INodeImagePluginOptions {
  /** Directory prefix for resolving relative local file paths (default: "") */
  pathPrefix?: string;

  /** Fallback format for SVGs or unsupported image types (default: "png") */
  fallbackImageType?: "png" | "jpg" | "gif";

  /** Maximum image width in inches (default: 6) */
  maxW?: number;

  /** Maximum image height in inches (default: 8) */
  maxH?: number;

  /** Target DPI for physical dimension calculation (default: 96) */
  dpi?: number;

  /** Custom placeholder image source (path, URL, or data URL) */
  placeholder?: string;

  /**
   * General image error behavior:
   * - "warn": Emits a styled muted text badge with alt text (default).
   * - "silent": Drops the image node completely.
   * - "throw": Rejects toDocx conversion promise with the underlying Error.
   * - "placeholder": Inserts options.placeholder image.
   */
  errorMode?: "warn" | "silent" | "throw" | "placeholder";

  /**
   * Fallback strategy for failed Mermaid diagrams:
   * - "code": Renders raw Mermaid code in a formatted Word code block (default).
   * - "warn": Emits a warning badge [Mermaid Diagram Error: ...].
   * - "silent": Drops the node completely.
   */
  mermaidFallback?: "code" | "warn" | "silent";

  /**
   * Fallback strategy for failed non-Mermaid SVGs:
   * - "warn": Emits styled muted text badge (default).
   * - "code": Renders raw SVG XML in a Word code block (`lang: "xml"`).
   * - "silent": Drops the node completely.
   */
  svgFallback?: "warn" | "code" | "silent";

  /**
   * Optional heading added above fallback code blocks (H6 level, maps to Word Heading 5).
   * - true: Injects '###### ⚠️ Diagram Source (Render Fallback)' (default).
   * - false: Omits the heading.
   * - string: Injects custom heading text.
   */
  collapsibleHeading?: boolean | string;

  /** Custom resolver function overriding the default fetch/sharp pipeline */
  imageResolver?: NodeImageResolver;
}