Overview

✨ FeaturesCopy Anchor Link

• ⚡ Lightweight & Fast: Direct conversion from Markdown Abstract Syntax Trees (MDAST) into native OpenXML Word structures.
• 🌐 Dual-Runtime Compatibility: Runs 100% in-browser (Blob, zero server required) and on server runtimes (Buffer, Uint8Array in Node.js, Next.js, Cloudflare Workers).
• 📑 Section & Layout Control: Multi-section documents with individual page sizes, orientation (Portrait/Landscape), margins, headers, and footers.
• 🔌 Extensible Plugin Pipeline: Rich lifecycle hooks (preprocess, inline, block, postprocess) for images, diagrams, math equations, and HTML.
• 🛡️ Defensive & Resilient: Built-in warning deduplication (warnOnce), safe error fallbacks, and non-mutating option handling.
• 💾 Persistent Caching Engine: Multi-tiered cache (@m2d/core/cache) using IndexedDB and in-memory caches with timestamped TTL and lock-free concurrency.

📦 InstallationCopy Anchor Link

$ pnpm add @m2d/core docx

or

$ npm install @m2d/core docx

or

$ yarn add @m2d/core docx

🚀 Quick StartCopy Anchor Link

Convert a Markdown string to a Word .docx file in just a few lines:

import { toDocx } from "@m2d/core";
import remarkParse from "remark-parse";
import remarkGfm from "remark-gfm";
import { unified } from "unified";

// 1. Parse Markdown into an MDAST tree
const markdown = "# Project Overview\n\nGenerated with **@m2d/core**.";
const mdast = unified().use(remarkParse).use(remarkGfm).parse(markdown);

// 2. Convert MDAST to a DOCX Blob (or 'buffer' on server)
const docxBlob = await toDocx(mdast, {
  title: "Project Overview",
  creator: "md2docx",
});

// 3. In the browser, trigger download or save
const url = URL.createObjectURL(docxBlob as Blob);
const a = document.createElement("a");
a.href = url;
a.download = "document.docx";
a.click();

🔌 Official Plugins EcosystemCopy Anchor Link

@m2d/core stays lean by delegating domain-specific nodes to modular plugins. Install only what you need:

Using PluginsCopy Anchor Link

import { toDocx } from "@m2d/core";
import { tablePlugin } from "@m2d/table";
import { imagePlugin } from "@m2d/image";

const docxBlob = await toDocx(mdast, {}, {
  plugins: [tablePlugin(), imagePlugin()],
});

📜 API ReferenceCopy Anchor Link

toDocx(astInputs, docxProps?, defaultSectionProps?, outputType?)Copy Anchor Link

function toDocx(
  astInputs: Root | { ast: Root; props?: ISectionProps }[],
  docxProps?: IDocxProps,
  defaultSectionProps?: IDefaultSectionOptions,
  outputType?: "blob" | "buffer" | "arraybuffer",
): Promise<Blob | Buffer | ArrayBuffer | Uint8Array>;

ParametersCopy Anchor Link

• astInputs: An MDAST Root node, or an array of section descriptors { ast: Root, props?: ISectionProps }[] for multi-section documents.
• docxProps (optional): Global document properties passed to docx.Document (title, author, subject, styles, etc.).
• defaultSectionProps (optional): Layout and conversion configuration applied to sections:
  • useTitle (boolean, default: true): Maps top-level # Heading to Word's Title style and demotes nested headings proportionally.
  • plugins (IPlugin[]): Array of conversion plugins.
  • trimInnerSpaces (boolean, default: true): Normalizes repeated whitespace in text runs.
  • Plus standard docx ISectionOptions (margins, paper size, orientation, headers, footers).
• outputType (optional, default: 'blob'): Target binary format ("blob", "buffer", or "arraybuffer").

📚 Deep Dive Guides & ArchitectureCopy Anchor Link

Explore our dedicated documentation guides for advanced configurations and internal know-how:

• ⚡ Caching Architecture Guide: Multi-tiered cache design, why TTL avoids write-amplification, lock-free IndexedDB concurrency, and shouldCache validation.
• 🔌 Plugin Authoring Guide: How to create custom plugins, hook into preprocess, block, inline, and postprocess lifecycles, and handle errors.
• 📑 Sections & Layout Guide: Crafting multi-section documents, landscape pages, custom margins, and heading hierarchy.

LicenseCopy Anchor Link

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

with 💖 by Mayank Kumar Chaudhari