@mdast2docx/image
Version:
MDAST to DOCX plugin for resolving and embedding images. Supports base64, URLs, and custom resolvers for seamless DOCX image integration.
222 lines (153 loc) • 6.94 kB
Markdown
# `@m2d/image` <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" height="40"/>
[](https://github.com/md2docx/image/actions/workflows/test.yml) [](https://codeclimate.com/github/md2docx/image/maintainability) [](https://codecov.io/gh/md2docx/image) [](https://www.npmjs.com/package/@m2d/image) [](https://www.npmjs.com/package/@m2d/image) 
> Converts Markdown (``), 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
```bash
npm install @m2d/image
```
```bash
pnpm add @m2d/image
```
```bash
yarn add @m2d/image
```
## 🚀 Overview
The `@m2d/image` plugin for [`mdast2docx`](https://github.com/mayankchaudhari/mdast2docx) renders image nodes in DOCX output.
It supports:
- Markdown image syntax: ``
- 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
```ts
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
```ts
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.
```ts
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**: ``
- **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`](https://npmjs.com/package/@m2d/core) | Converts extended MDAST to DOCX |
| [`@m2d/html`](https://npmjs.com/package/@m2d/html) | Parses raw HTML to extended MDAST |
| [`@m2d/mermaid`](https://npmjs.com/package/@m2d/mermaid) | Adds mermaid diagrams as SVG/image nodes |
| [`@m2d/table`](https://npmjs.com/package/@m2d/table) | Renders table nodes to DOCX |
| [`@m2d/list`](https://npmjs.com/package/@m2d/list) | Enhanced list support (tasks, bullets) |
## ⭐ Support Us
If you find this useful:
- ⭐ Star [mdast2docx](https://github.com/tiny-md/mdast2docx) on GitHub
- ❤️ Consider [sponsoring](https://github.com/sponsors/mayank1513)
## 🧾 License
MIT © [Mayank Chaudhari](https://github.com/mayankchaudhari)
<p align="center">Made with 💖 by <a href="https://mayank-chaudhari.vercel.app" target="_blank">Mayank Kumar Chaudhari</a></p>