@mdast2docx/remark-docx
v1.6.0
Published
A unified plugin to prepare MDAST trees for DOCX conversion using mdast2docx.
Maintainers
Keywords
Readme
@m2d/remark-docx
@m2d/remark-docx: Unified & Remark compiler plugin that transforms Markdown directly into Microsoft Word (
.docx) documents.
✨ Features
- 🔌 Unified & Remark Compiler: Plugs directly into
unified().use(remarkDocx)to compile MDAST syntax trees into Word OpenXML. - 📦 Auto-Injected Plugins: Automatically configures tables, math, lists, images, emojis, and HTML plugins when none are specified.
- 🌐 Isomorphic Execution: Runs in both browser (generating client-side
Blobs) and Node.js (generatingBuffers for file writing). - ⚙️ Configurable Outputs: Supports
"blob","buffer","base64", and"uint8array"formats. - ⚡ Dual Execution APIs: Compatible with both async
.process()and synchronous.processSync()pipelines.
📦 Installation
[!TIP] This package (@mdast2docx/remark-docx) is an official alias of @m2d/remark-docx.
We provide this package to offer shorter import paths and improved discoverability. While both packages provide identical functionality, @m2d/remark-docx is the primary source of truth.
- Use @mdast2docx/remark-docx if you prefer the shorter name or specific branding or ESM Only.
- Use @m2d/remark-docx for the most stable long-term reference and standard alignment.
| Feature | @m2d/remark-docx | @mdast2docx/remark-docx | | --- | --- | --- | | 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) |
Security: Security audits are performed on the canonical package; this alias inherits all security patches automatically.
$ pnpm add @m2d/remark-docx docx unified remark-parse remark-gfmor
$ npm install @m2d/remark-docx docx unified remark-parse remark-gfmor
$ yarn add @m2d/remark-docx docx unified remark-parse remark-gfm🚀 Quick Start
Browser (Download as DOCX)
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkGfm from "remark-gfm";
import { remarkDocx } from "@m2d/remark-docx";
const processor = unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkDocx, "blob");
const file = await processor.process(
"# Hello World\n\nExported directly to Word!",
);
const blob = (await file.result) as Blob;
// Trigger browser download
const url = URL.createObjectURL(blob);
const link = document.createElement("a");
link.href = url;
link.download = "document.docx";
link.click();
URL.revokeObjectURL(url);Node.js (with Native Images & Mermaid Support)
For Node.js environments, use @m2d/remark-docx-node to automatically wire native server-side image resolution (@m2d/image-node) and diagram rendering (@m2d/mermaid-node):
import fs from "node:fs/promises";
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkGfm from "remark-gfm";
import { remarkDocx } from "@m2d/remark-docx-node";
const processor = unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkDocx, "buffer");
const file = await processor.process(
"# Server Report\n\nWritten via Node.js with native image and Mermaid rasterization.",
);
const buffer = (await file.result) as Buffer;
await fs.writeFile("report.docx", buffer);⚙️ Plugin Signature
import { OutputType } from "docx";
import { IDocxProps, ISectionProps } from "mdast2docx";
remarkDocx(
outputType?: "blob" | "buffer" | "base64" | "uint8array", // Default: "blob"
docxProps?: IDocxProps, // Global Word document options (title, styles, definitionsScope: "shared" | "section")
sectionProps?: ISectionProps, // Section margins, headers, and plugins
pluginProps?: { // Options passed to auto-injected plugins
table?: TablePluginOptions;
list?: ListPluginOptions;
mermaid?: MermaidPluginOptions;
image?: ImagePluginOptions;
emoji?: EmojiPluginOptions;
}
);📚 Deep Dive Guides
- 🔌 Unified Pipeline Integration Guide: Architecture, plugin auto-injection, and manual plugin overrides.
- 💾 Output Formats & Environments Guide: Browser downloads, server writing, sync execution, and binary output types.
License
This library is licensed under the MIT open-source license.
