mdast-to-docx

MDAST (Markdown Abstract Syntax Tree) to DOCX

🚀 Effortlessly convert Markdown Abstract Syntax Trees (MDAST) to DOCX.

✨ Features

✅ MDAST to DOCX conversion — Supports standard Markdown elements
✅ Footnotes handling — Converts Markdown footnotes to DOCX format
✅ Tables support — Converts Markdown tables into DOCX tables
✅ Hyperlink support — External and internal hyperlinks are now fully functional
✅ New Plugin Architecture — Extend and customize DOCX output with plugins
✅ Customizable image handling — Images are now supported via @m2d/image plugin

Note: Images are no longer supported by default. To enable image support, use the image plugin from @m2d/image or mdast2docx/plugins explicitly.
This change helps us keep the library lean and extensible by community via plugins.

🚀 Relevance to Generative AI

Converts markdown content/artifacts generated by Generative AI to docx for further processing/record-keeping/sharing.

Modern Generative AI tools often produce structured content in Markdown (MD) format. However, converting this AI-generated Markdown into professional DOCX documents requires an additional transformation step. This is where MDAST to DOCX comes in.

How It Works

• AI tools generate content in Markdown.
• Unified.js & Remark Ecosystem convert Markdown into Markdown Abstract Syntax Tree (MDAST).
• MDAST to DOCX processes this structure and exports a well-formatted DOCX document.

Use Cases

• AI-Generated Reports – Convert AI-generated Markdown reports into polished DOCX files.
• AI-Powered Content Export – Transform AI-generated blogs, research papers, and structured content into a DOCX format for easy sharing and editing.
• Client & Server Flexibility – Works both in browser-based AI tools and high-performance server environments.

✅ Benefits

• Works on both Client & Server – Choose to offload processing to the client for better scalability or run it on the server for batch conversions.
• Optimized & Extensible – Use only the plugins you need, keeping your AI workflows lightweight.

By integrating MDAST to DOCX, AI applications can seamlessly export Markdown-based content into DOCX, making it more accessible, editable, and shareable. 🚀

📦 Installation

Install Everything at Once

pnpm add mdast2docx

Or Install Only What You Need (Scoped Packages)

pnpm add @m2d/core @m2d/html @m2d/image @m2d/math @m2d/table @m2d/list @m2d/mdast

🚀 Usage

Basic Example

import { toDocx } from "mdast2docx";
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkMmd from "remark-mmd"; // Assumed MMD plugin

const markdown = `
# Sample Document  
This is a **bold** text and _italic_ text.  

> A blockquote example  

- List Item 1  
- List Item 2  

[Click Here](https://example.com)  

This is a footnote reference[^1].  

[^1]: This is the footnote content.
`;

const mdast = unified().use(remarkParse).use(remarkMmd).parse(markdown);

(async () => {
  const docxBlob = await toDocx(mdast, { title: "My Document" }, {});
  const url = URL.createObjectURL(docxBlob as Blob);
  const link = document.createElement("a");
  link.href = url;
  link.download = "document.docx";
  link.click();
  URL.revokeObjectURL(url);
})();

📜 API Reference

toDocx(astInputs, docxProps, defaultSectionProps, outputType?)

Parameter	Type	Description
astInputs	Root | { ast: Root; props?: ISectionProps }[]	Single or multiple MDAST trees with optional section properties.
docxProps	IDocxProps	General document properties (title, styles, metadata).
defaultSectionProps	ISectionProps	Default properties for document sections.
outputType (optional)	"blob" (default) | "buffer" | "base64"	Format of the generated DOCX document.

📌 Returns: A Promise resolving to a DOCX document in the chosen format.

📜 Supported Markdown Elements

Markdown Syntax	Supported in DOCX
Headings # H1 to ###### H6	✅
Paragraphs	✅
Bold **text** & Italics _text_	✅
Blockquotes > quote	✅
Lists (ordered & unordered)	✅ (ordered lists via listPlugin)
Links [text](url)	✅
Images 	✅ (via imagePlugin)
Code Blocks `code`	✅
Footnotes [^1]	✅
Tables	✅ (via tablePlugin)
Hyperlinks (external & internal)	✅
Latex Math	✅ (via mathPlugin)
HTML Tags	✅ (via htmlPlugin)

🔧 Configuration

You can customize the DOCX output using ISectionProps and IDocxProps.

Example: Customizing Styles

const docxProps = {
  title: "Styled Document",
  author: "John Doe",
};

const sectionProps = {
  page: { margin: { top: 1000, bottom: 1000, left: 1200, right: 1200 } },
};

const docxBlob = await toDocx(mdast, docxProps, sectionProps);

Use Plugins

Plugins allow extending functionality like adding image or table support.

import { toDocx } from "@m2d/core";
import { imagePlugin } from "@m2d/image";
import { tablePlugin } from "@m2d/table";
import { listPlugin } from "@m2d/list";
import { mathPlugin } from "@m2d/math";

const downloadDocx = () => {
  toDocx(
    mdast,
    {},
    { plugins: [imagePlugin(), tablePlugin(), listPlugin(), mathPlugin()] },
    "blob",
  ).then(blob => {
    const url = URL.createObjectURL(blob as Blob);
    const link = document.createElement("a");
    link.href = url;
    link.download = "my-document.docx";
    link.click();
    URL.revokeObjectURL(url);
  });
};

📖 More details:

• DOCX.js Document Properties
• DOCX.js Section Options

🧠 Relevance in Generative AI

AI tools often generate Markdown as output (e.g., reports, documentation, summaries). This library makes it easy to convert those Markdown-based outputs into rich DOCX documents.

• Supports both client-side and server-side usage
• Enables offloading document generation to users' browsers or running high-performance server renderers
• Combine it with unified and remark to parse Markdown into MDAST, and then convert to DOCX seamlessly

📝 Contributing

We welcome contributions! To get started:

• Fork the repository
• Create a feature branch (git checkout -b feature-new)
• Commit your changes (git commit -m "Add new feature")
• Push to GitHub (git push origin feature-new)
• Open a Pull Request 🚀

Extend Functionality with Plugins

The community can create plugins to extend the functionality of this library. For inspiration, check out the existing plugins in the lib/src/plugins folder.

📄 License

This project is licensed under MPL-2.0. See the LICENSE file for details.

🙌 Acknowledgments

Thanks to the docx.js and unified.js ecosystems for making this possible.

⭐ Star this repository if you find it useful!
❤️ Support our work by sponsoring.

Made with 💖 by Mayank Kumar Chaudhari