Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/md2docx/mdast2docx

Utility to convert MDAST (Markdown Abstract Syntax Tree) to DOCX
https://github.com/md2docx/mdast2docx

ai converter docx generative-ai javascript mayank1513 nodejs remark remark-plugin remark-plugins typescript unified

Last synced: 3 months ago
JSON representation

Utility to convert MDAST (Markdown Abstract Syntax Tree) to DOCX

Awesome Lists containing this project

README 

        
# **MDAST (Markdown Abstract Syntax Tree) to DOCX** 



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



[![Test](https://github.com/md2docx/mdast2docx/actions/workflows/test.yml/badge.svg)](https://github.com/md2docx/mdast2docx/actions/workflows/test.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/md2docx/mdast2docx/maintainability) [![Code Coverage](https://codecov.io/gh/md2docx/mdast2docx/graph/badge.svg)](https://codecov.io/gh/md2docx/mdast2docx) [![Version](https://img.shields.io/npm/v/mdast2docx.svg?colorB=green)](https://www.npmjs.com/package/mdast2docx) [![Downloads](https://img.shields.io/npm/d18m/mdast2docx)](https://www.npmjs.com/package/mdast2docx) ![Bundle Size](https://img.shields.io/bundlephobia/minzip/mdast2docx)



---



## **✨ 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**



1. **AI tools generate content in Markdown**.

2. **Unified.js & Remark Ecosystem** convert Markdown into **Markdown Abstract Syntax Tree (MDAST)**.

3. **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**



```bash

pnpm add mdast2docx

```



### **Or Install Only What You Need (Scoped Packages)**



```bash

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

```



---



## **🚀 Usage**



### **Basic Example**



```typescript

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 `![alt](url)`               | ✅ _(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**



```typescript

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.



```typescript

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](https://docx.js.org/#/usage/document)

- [DOCX.js Section Options](https://docx.js.org/#/usage/sections)



---



## **🧠 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:



1. **Fork** the repository

2. **Create a feature branch** (`git checkout -b feature-new`)

3. **Commit your changes** (`git commit -m "Add new feature"`)

4. **Push to GitHub** (`git push origin feature-new`)

5. **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`](https://github.com/md2docx/mdast2docx/tree/main/lib/src/plugins) folder.



---



## **📄 License**



This project is **licensed under MPL-2.0**. See the [LICENSE](./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](https://github.com/sponsors/mayank1513).



---



Made with 💖 by Mayank Kumar Chaudhari