Skip to content

Latest commit

 

History

History

remark-docx

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

@m2d/remark-docx

CI codecov npm version npm downloads npm bundle size license

@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 (generating Buffers 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

$ pnpm add @m2d/remark-docx docx unified remark-parse remark-gfm

or

$ npm install @m2d/remark-docx docx unified remark-parse remark-gfm

or

$ 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


License

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


with 💖 by Mayank Kumar Chaudhari