https://github.com/md2docx/remark-docx
A Unified/Remark plugin that injects a DOCX compiler using [`mdast2docx`](https://github.com/tiny-md/mdast2docx) and outputs `.docx` files from Markdown.
https://github.com/md2docx/remark-docx
Last synced: 10 months ago
JSON representation
A Unified/Remark plugin that injects a DOCX compiler using [`mdast2docx`](https://github.com/tiny-md/mdast2docx) and outputs `.docx` files from Markdown.
- Host: GitHub
- URL: https://github.com/md2docx/remark-docx
- Owner: md2docx
- License: mpl-2.0
- Created: 2025-03-26T03:23:18.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-02T08:13:48.000Z (about 1 year ago)
- Last Synced: 2025-04-02T09:26:18.390Z (about 1 year ago)
- Language: TypeScript
- Size: 854 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# @m2d/remark-docx 
[](https://github.com/md2docx/remark-docx/actions/workflows/test.yml) [](https://codecov.io/gh/md2docx/remark-docx) [](https://www.npmjs.com/package/@m2d/remark-docx)
> A Unified/Remark plugin that injects a DOCX compiler using [`mdast2docx`](https://github.com/md2docx/mdast2docx) and outputs `.docx` files from Markdown.
---
## 🧭 Overview
`@m2d/remark-docx` enables direct export of Markdown content to Microsoft Word (`.docx`) using the Unified ecosystem. It seamlessly bridges `remark` with the [`mdast2docx`](https://github.com/md2docx/mdast2docx) compiler and auto-injects common plugins like GFM tables, math, lists, and inline HTML support.
It’s designed for both **browser** and **Node.js** environments, handling environment-specific features like image or HTML parsing smartly.
---
## ✨ Features
- 📄 Converts Markdown to `.docx` using `mdast2docx`
- 🔌 Auto-injects plugins for GFM tables, math, lists, images, and HTML
- 🧠 Smart: excludes DOM-only plugins in Node.js
- 💥 Supports both `.process()` and `.processSync()` with an async `.result`
- 🔄 Output as `Blob`, `Buffer`, or `base64`
---
## 📦 Installation
```bash
npm install @m2d/remark-docx docx
```
Also install any optional plugins you wish to include in your pipeline:
```bash
npm install remark-parse remark-gfm remark-math remark-frontmatter
```
Other package managers:
```bash
yarn add @m2d/remark-docx docx
pnpm add @m2d/remark-docx docx
```
---
## 🚀 Usage
### 🔗 Browser Example (Async)
```ts
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkGfm from "remark-gfm";
import remarkMath from "remark-math";
import remarkFrontmatter from "remark-frontmatter";
import { remarkDocx } from "@m2d/remark-docx";
const processor = unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkFrontmatter)
.use(remarkMath)
.use(remarkDocx);
const downloadDocx = () => {
processor
.process(md)
.then(res => res.result)
.then(blob => {
const url = URL.createObjectURL(blob as Blob);
const link = document.createElement("a");
link.href = url;
link.download = "document.docx";
link.click();
URL.revokeObjectURL(url);
});
};
```
### ⚡ Browser Example (Sync + Async Result)
```ts
const { result } = processor.processSync(md) as { result: Promise };
result.then(blob => {
const url = URL.createObjectURL(blob);
const link = document.createElement("a");
link.href = url;
link.download = "document.docx";
link.click();
URL.revokeObjectURL(url);
});
```
---
### 🐢 Node.js Example
```ts
import fs from "node:fs";
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkGfm from "remark-gfm";
import remarkMath from "remark-math";
import remarkFrontmatter from "remark-frontmatter";
import { remarkDocx } from "@m2d/remark-docx";
const markdown = `
# Hello DOCX
This is a *Markdown* document with **tables**, math, and more.
| A | B |
|---|---|
| 1 | 2 |
Inline math: $x^2 + y^2 = z^2$
`;
const processor = unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkFrontmatter)
.use(remarkMath)
.use(remarkDocx, "buffer"); // outputType = "buffer" in Node
const { result } = processor.processSync(markdown) as { result: Promise };
result.then(buffer => {
fs.writeFileSync("output.docx", buffer);
console.log("✔ DOCX file written: output.docx");
});
```
---
## 🧩 Plugin Behavior
By default, these `mdast2docx` plugins are included:
| Plugin | Description |
| ------------- | ----------------------- |
| `htmlPlugin` | Parses inline HTML |
| `tablePlugin` | GFM table support |
| `listPlugin` | Ordered/unordered lists |
| `mathPlugin` | KaTeX math blocks |
| `imagePlugin` | Resolves images |
On **Node.js**, `htmlPlugin` and `imagePlugin` are automatically excluded to avoid DOM dependency issues.
To override this behavior, pass custom plugins using `sectionProps.plugins`.
---
## 📘 API
### `remarkDocx(outputType?, docxProps?, sectionProps?)`
| Param | Type | Description |
| -------------- | ------------------------------------ | ----------------------------------- |
| `outputType` | `"blob"` \| `"buffer"` \| `"base64"` | Default is `"blob"` |
| `docxProps` | `IDocxProps` | Global DOCX config (optional) |
| `sectionProps` | `ISectionProps` | Section + plugin control (optional) |
Returns a `Processor` where `.result` on `vfile` is a `Promise` depending on the mode.
---
## 🔥 Output Handling
Both `.process()` and `.processSync()` return a `vfile` with a `result` field:
```ts
const file = await processor.process(md);
const blobOrBuffer = await file.result;
```
> This makes the plugin environment-safe and decoupled from internal mutation or I/O.
---
## 🛠 Development
```bash
npm run dev # Watch mode
npm run build # Compile to /dist
npm run lint # Lint source
npm run test # Run tests
```
---
## 📄 License
Licensed under the [MPL-2.0 License](https://www.mozilla.org/en-US/MPL/2.0/).
---
## 💖 Sponsors
Support the project & its ecosystem:
- [@md2docx](https://github.com/sponsors/md2docx)
- [@mayank1513](https://github.com/sponsors/mayank1513)
---
## 🔗 Related Projects
- [`mdast2docx`](https://github.com/md2docx/mdast2docx) – The DOCX engine
- [`docx`](https://github.com/dolanmiu/docx) – Low-level DOCX generation
- [`unified`](https://unifiedjs.com) – Processor pipeline
- [`remark`](https://github.com/remarkjs/remark) – Markdown parser
---
Made with 💖 by Mayank Kumar Chaudhari