# @md2docx/image

> MDAST to DOCX plugin for resolving and embedding images. Supports base64, URLs, and custom resolvers for seamless DOCX image integration.

Latest version **1.6.0** (published 2026-10-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @md2docx/image
pnpm add @md2docx/image
yarn add @md2docx/image
bun add @md2docx/image
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.6.0 |
| Published | 2026-10-22 |
| First published | 2025-03-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 9.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Mayank Kumar Chaudhari |
| Maintainers | mayank1513 |
| Keywords | images, image-plugin, image-resolver, image-embedding, base64, remote-image, docx-image, mdast, markdown, markdown-to-docx, mdast-to-docx, md2docx, mdast2docx, plugin, converter, remark, unified, docx, ms-word, document-generator, document-generation, text-processing, typescript, open-source, customizable, modern, seamless-integration, cutting-edge, compatibility, progressive, web-development, frontend, automation, export, google-sheets, generative-ai, rich-text, hyperlinks, footnotes, m2d, mayank1513 |

## Links

- npm: https://www.npmjs.com/package/@md2docx/image
- Repository: https://github.com/md2docx/md2docx
- Homepage: https://github.com/md2docx/md2docx/blob/main/packages/image/README.md
- Issues: https://github.com/md2docx/md2docx/issues
- Funding: https://github.com/sponsors/md2docx
- npm.io page: https://npm.io/package/@md2docx/image

## Dependencies (1)

- [@m2d/image](https://npm.io/package/@m2d/image.md) 1.6.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 1.6.0 (latest) — 2026-10-22
- 1.4.1 — 2025-09-26
- 1.4.0 — 2025-09-26
- 1.3.2 — 2025-09-24
- 1.3.1 — 2025-06-12
- 1.3.0 — 2025-06-12
- 1.2.1 — 2025-06-06
- 1.2.0 — 2025-06-02
- 1.1.3 — 2025-06-02
- 1.1.2 — 2025-06-01
- 1.1.1 — 2025-05-30
- 1.1.0 — 2025-05-26
- 1.0.1 — 2025-05-20
- 1.0.0 — 2025-05-19
- 0.2.4 — 2025-04-28
- … 7 more at https://npm.io/package/@md2docx/image/versions

## README

# @m2d/image <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>

<p className="flex gap-2">
  <a href="https://github.com/md2docx/md2docx/actions/workflows/ci.yml" rel="noopener noreferrer">
    <img alt="CI" src="https://github.com/md2docx/md2docx/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://codecov.io/gh/md2docx/md2docx/tree/main/packages/@m2d/image" rel="noopener noreferrer">
    <img alt="codecov" src="https://codecov.io/gh/md2docx/md2docx/graph/badge.svg?flag=@m2d/image" />
  </a> 
  <a href="https://npmjs.com/package/@m2d/image" rel="noopener noreferrer">
    <img alt="npm version" src="https://img.shields.io/npm/v/@m2d/image" />
  </a>
  <a href="https://npmjs.com/package/@m2d/image" rel="noopener noreferrer">
    <img alt="npm downloads" src="https://img.shields.io/npm/d18m/@m2d/image" />
  </a>
  <a href="https://npmjs.com/package/@m2d/image" rel="noopener noreferrer">
    <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/@m2d/image" />
  </a>
  <img alt="license" src="https://img.shields.io/npm/l/@m2d/image" />
</p>

> @m2d/image: Client-side image and SVG rasterization plugin for `@m2d/core`. Converts Markdown `![alt](url)`, HTML `<img>`, and diagram SVGs into DOCX-compatible `ImageRun` elements in browser environments.

---

## ✨ Features

- 🖼️ **Universal Image Resolution**: Resolves Markdown `![alt](url)`, HTML `<img>`, Base64 data URIs, and SVG elements into OpenXML DrawingML pictures.
- 🎨 **Client-Side Canvas Rasterization**: High-fidelity in-browser SVG-to-raster conversion via HTML5 Canvas.
- 🛡️ **Configurable Error Policies**: Supports `"warn"`, `"silent"`, `"throw"`, and `"placeholder"` modes on image load or network failures.
- 📊 **Diagram Code Fallbacks**: Automatically transforms failed Mermaid diagrams and raw SVGs into authentic Word code blocks with borders and Consolas styling.
- 📂 **Collapsible Headings in Word**: Injects collapsible `H6` headings (Word `Heading 5`) above fallback code blocks without cluttering standard 1–3 level Tables of Contents.
- 💾 **IndexedDB & Memory Caching**: Lock-free multi-tier caching prevents duplicate image fetches and canvas conversions.

> 💡 **Looking for server-side (Node.js) image resolution?** Use [`@m2d/image-node`](https://npmjs.com/package/@m2d/image-node) powered by `sharp`.

---

## 📦 Installation


> [!TIP]
> **This package (@md2docx/image) is an official alias of [@m2d/image](https://npmjs.com/package/@m2d/image).**

<details>
<summary>Why does this exist?</summary>

We provide this package to offer shorter import paths and improved discoverability. While both packages provide identical functionality, **@m2d/image** is the primary source of truth.
</details>

<details>
<summary>Which one should I use?</summary>

* **Use @md2docx/image** if you prefer the shorter name or specific branding or ESM Only.
* **Use @m2d/image** for the most stable long-term reference and standard alignment.

| Feature | @m2d/image | @md2docx/image |
| --- | --- | --- |
| **Source Code** | ✅ Primary | 🔗 Proxy |
| **Updates** | Immediate | Synchronized (Immediately) |
| **Bundle Size** | 100% | 100% (Zero overhead) |
| **Format** | ESM + CJS | ESM Only |
| **Maintenance** | ✅ Primary | 🔗 Proxy (inherits) |
| **Security** | ✅ Primary | 🔗 Proxy (inherits) |

</details>

<details>
<summary>Maintenance & Support</summary>

> **Security:** Security audits are performed on the canonical package; this alias inherits all security patches automatically.
</details>

---



```bash
$ pnpm add @m2d/image @m2d/core docx
```

**_or_**

```bash
$ npm install @m2d/image @m2d/core docx
```

**_or_**

```bash
$ yarn add @m2d/image @m2d/core docx
```

---

## 🚀 Quick Start

```typescript
import { toDocx } from "@m2d/core";
import { imagePlugin } from "@m2d/image";
import { mermaidPlugin } from "@m2d/mermaid";
import remarkParse from "remark-parse";
import { unified } from "unified";

const markdown = `
# Document With Images

![Architecture Diagram](https://example.com/arch.png)

\`\`\`mermaid
graph TD
  A[Start] --> B[Finish]
\`\`\`
`;

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

const docxBlob = await toDocx(mdast, {}, {
  plugins: [
    mermaidPlugin(), // Generates SVG nodes
    imagePlugin(),   // Converts images and diagram SVGs to DOCX ImageRuns
  ],
});
```

> ⚠️ **Plugin Ordering**: When combining with diagram plugins like `@m2d/mermaid` or HTML plugins like `@m2d/html`, place `imagePlugin()` **after** them in the `plugins` array.

---

## ⚙️ Plugin Options

```typescript
export interface IImagePluginOptions {
  /** Maximum image width in inches (default: 6) */
  maxW?: number;

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

  /** Resolution scaling factor for base64 images (default: 3) */
  scale?: number;

  /** Quality factor (0-1) for lossy image formats (default: 0.92) */
  quality?: number;

  /** Fallback image format to convert unsupported types (default: "png") */
  fallbackImageType?: "png" | "jpg";

  /** 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 the 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 image resolver function */
  imageResolver?: ImageResolver;

  /** Cache configuration or sharing across instances */
  cache?: Record<string, Promise<unknown>>;
  maxAgeMinutes?: number; // default: 10080 (7 days)
}
```

---

## 📚 Deep Dive Guides

Explore our detailed documentation guides:

- 🛡️ **[Error Handling & Fallbacks Guide](./docs/error-handling-and-fallbacks.mdx)**: Comprehensive guide on error modes, collapsible headings, and Word TOC safety.
- 🔌 **[Custom Resolvers & Caching Guide](./docs/custom-resolvers-and-caching.mdx)**: Authenticated image fetching, custom headers, and multi-tier IndexedDB cache configuration.

---

## License

This library is licensed under the MIT open-source license.

<hr />

<p align="center">with 💖 by <a href="https://mayankchaudhari.com" target="_blank">Mayank Kumar Chaudhari</a></p>

---
_Source: https://npm.io/package/@md2docx/image · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._