mdast2docx 1.4.2 → 1.5.0

package/README.md

@@ -1,58 +1,47 @@
 # **MDAST (Markdown Abstract Syntax Tree) to DOCX** <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
 
-🚀 **Effortlessly convert Markdown Abstract Syntax Trees (MDAST) to DOCX.**
+**🚀 A powerful, modular, and extensible Markdown to DOCX converter.**
 
-[![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)
+<p align="center">
+  <img src="./banner.svg" alt="logo" style="height: 360px; margin:auto" />
+</p>
 
----
-
-## **✨ 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
+MD2DOCX is a robust library for converting Markdown Abstract Syntax Trees (MDAST) into DOCX documents. Built on the powerful `unified.js` and `docx.js` ecosystems, it offers a flexible, plugin-driven architecture that works seamlessly on both the client and server.
 
-> **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.
+[![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)
 
 ---
 
-## **🚀 Relevance to Generative AI**
-
-<details open>
-<summary>
-<i>Converts markdown content/artifacts generated by Generative AI to docx for further processing/record-keeping/sharing.</i>
-</summary>
-
-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**
+## ✨ Key Features
 
-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**.
+- **Modular Architecture**: Keep your bundles small. The core is lightweight, and you can add features like tables, images, or math support via plugins.
+- **Comprehensive Markdown Support**: Handles all standard Markdown syntax, including headings, lists, links, code blocks, and more.
+- **Client & Server Ready**: Isomorphic design works flawlessly in both Node.js and browser environments.
+- **Highly Customizable**: Leverage the full power of `docx.js` to style your document, including headers, footers, margins, and paragraph styles.
+- **Scoped Packages**: Install only what you need using `@m2d/*` packages, or grab the all-in-one `mdast2docx` package.
 
-### **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**
+## 🤖 The Generative AI Power-Up
 
-- **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.
+Modern **Generative AI** tools often produce structured content in **Markdown**. This library acts as the perfect bridge to convert AI-generated artifacts into professionally formatted DOCX documents for editing, sharing, or record-keeping.
 
-By integrating **MDAST to DOCX**, AI applications can **seamlessly export Markdown-based content into DOCX**, making it more accessible, editable, and shareable. 🚀
+**Workflow:** `AI Output (Markdown)` → `unified/remark (MDAST)` → `mdast2docx` → `Professional DOCX Document`
 
-</details>
+- **AI-Generated Reports**: Convert AI-generated summaries and reports into polished DOCX files.
+- **Content Export**: Transform AI-generated blogs, articles, and research into an editable DOCX format.
+- **Flexible Processing**: Offload document generation to the client for scalability or run it on the server for high-performance batch processing.
 
 ---
 
-## **📦 Installation**
+## 📦 Installation
+
+You can install the all-in-one package or select only the scoped packages you need.
 
 ### **Install Everything at Once**
 
@@ -60,182 +49,173 @@ By integrating **MDAST to DOCX**, AI applications can **seamlessly export Markdo
 pnpm add mdast2docx
 ```
 
-### **Or Install Only What You Need (Scoped Packages)**
+### **Or Install Only What You Need**
 
 ```bash
-pnpm add @m2d/core @m2d/html @m2d/image @m2d/math @m2d/table @m2d/list @m2d/mdast
+pnpm add @m2d/core @m2d/image @m2d/table  # and other plugins
 ```
 
 ---
 
-## **🚀 Usage**
+## 🚀 Usage
+
+You can use the library at a high level with `@m2d/remark-docx` for seamless integration with unified plugin system or at a lower level with `@m2d/core` + plugins ro `mdast2docx` for full control.
 
 ### **Basic Example**
 
+This example uses the core `toDocx` function to convert an MDAST object into a DOCX file and trigger a download in the browser.
+
 ```typescript
 import { toDocx } from "mdast2docx";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
-import remarkMmd from "remark-mmd"; // Assumed MMD plugin
 
+// 1. Your Markdown content
 const markdown = `
-# Sample Document  
-This is a **bold** text and _italic_ text.  
+# Sample Document
+This is a paragraph with **bold** and _italic_ text.
 
-> A blockquote example  
+> A blockquote.
 
-- List Item 1  
-- List Item 2  
+* List Item 1
+* List Item 2
 
-[Click Here](https://example.com)  
-
-This is a footnote reference[^1].  
-
-[^1]: This is the footnote content.
+[Visit our website](https://example.com)
 `;
 
-const mdast = unified().use(remarkParse).use(remarkMmd).parse(markdown);
+// 2. Parse Markdown to MDAST
+const mdast = unified().use(remarkParse).parse(markdown);
 
-(async () => {
-  const docxBlob = await toDocx(mdast, { title: "My Document" }, {});
+// 3. Convert MDAST to DOCX and download
+async function generateDocx() {
+  const docxBlob = await toDocx(mdast);
+
+  // Create a download link
   const url = URL.createObjectURL(docxBlob as Blob);
   const link = document.createElement("a");
   link.href = url;
   link.download = "document.docx";
+  document.body.appendChild(link);
   link.click();
+  document.body.removeChild(link);
   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.
+generateDocx();
+```
 
 ---
 
-## **📜 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`)_               |
-
----
+## 🔌 Plugins
 
-## **🔧 Configuration**
+The core library is intentionally lean. Use plugins to add support for features like images, tables, math equations, and more.
 
-You can customize the DOCX output using `ISectionProps` and `IDocxProps`.
+### **Example: Using Plugins**
 
-### **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.
+To use plugins, install them and pass them into the configuration. You can apply plugins globally to all sections using defaultSectionProps or specify them for each section individually.
 
 ```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";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm"; // For table support
+import remarkMath from "remark-math"; // For math support
+
+const markdownWithFeatures = `
+An image: ![alt text](https://via.placeholder.com/150)
+
+| Header 1 | Header 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+
+A math equation: $E = mc^2$
+`;
+
+const mdast = unified()
+  .use(remarkParse)
+  .use(remarkGfm) // Enable GFM for tables
+  .use(remarkMath) // Enable math syntax
+  .parse(markdownWithFeatures);
 
-const downloadDocx = () => {
-  toDocx(
+(async () => {
+  const docxBlob = await 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);
-  });
-};
+    {}, // docxProps
+    {
+      // Pass plugins in sectionProps
+      plugins: [imagePlugin(), tablePlugin(), mathPlugin()],
+    }
+  );
+  // ... download logic ...
+})();
 ```
 
-📖 **More details:**
+---
 
-- [DOCX.js Document Properties](https://docx.js.org/#/usage/document)
-- [DOCX.js Section Options](https://docx.js.org/#/usage/sections)
+## 📜 API Reference
 
----
+### **`toDocx(astInputs, docxProps?, sectionProps?, outputType?)`**
 
-## **🧠 Relevance in Generative AI**
+Converts one or more MDAST trees into a DOCX document.
 
-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.
+| Parameter      | Type            | Description                                                                                                                             |
+| :------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `astInputs`    | `Root`          | `{ ast: Root; props?: ISectionProps }[]`                                                                                                | A single MDAST root node or an array of nodes, each with optional section properties. |
+| `docxProps`    | `IDocxProps`    | Optional. Global document properties like title, author, and styles. See [docx.js docs](https://docx.js.org/#/usage/document).          |
+| `sectionProps` | `ISectionProps` | Optional. Default properties for document sections, like margins and plugins. See [docx.js docs](https://docx.js.org/#/usage/sections). |
+| `outputType`   | `"blob"`        | `"buffer"`                                                                                                                              | `"base64"`                                                                            | Optional. The output format. Defaults to `"blob"` in browsers and `"buffer"` in Node.js. |
 
-- 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
+**Returns:** `Promise<Blob | Buffer | string>` — A promise that resolves with the generated DOCX document in the specified format.
 
 ---
 
-## **📝 Contributing**
+## ✅ Supported Markdown Elements
+
+| Feature                | Supported | Plugin Required |
+| :--------------------- | :-------: | :-------------- |
+| Headings (`# H1`)      |    ✅     | **No**          |
+| Paragraphs             |    ✅     | **No**          |
+| Bold & Italic          |    ✅     | **No**          |
+| Blockquotes            |    ✅     | **No**          |
+| Links                  |    ✅     | **No**          |
+| Code Blocks            |    ✅     | **No**          |
+| Footnotes              |    ✅     | **No**          |
+| Unordered Lists        |    ✅     | **No**          |
+| Images `![alt](url)`   |    ✅     | `@m2d/image`    |
+| Tables (GFM)           |    ✅     | `@m2d/table`    |
+| Ordered Lists          |    ✅     | `@m2d/list`     |
+| Math Equations (LaTeX) |    ✅     | `@m2d/math`     |
+| Raw HTML               |    ✅     | `@m2d/html`     |
 
-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** 🚀
+## 🤝 Contributing
 
-### **Extend Functionality with Plugins**
+We welcome contributions\! Please feel free to fork the repository, create a feature branch, and open a pull request.
 
-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.
+1.  **Fork** the repository.
+2.  **Create a feature branch** (`git checkout -b feature/your-new-feature`).
+3.  **Commit your changes** (`git commit -m "Add a new feature"`).
+4.  **Push to the branch** (`git push origin feature/your-new-feature`).
+5.  **Open a Pull Request**. 🚀
 
 ---
 
-## **📄 License**
+## 📄 License
 
-This project is **licensed under MPL-2.0**. See the [LICENSE](./LICENSE) file for details.
+This project is licensed under the **MPL-2.0**. See the [LICENSE](./LICENSE) file for details.
 
 ---
 
-## **🙌 Acknowledgments**
+## 🙌 Acknowledgments
 
-Thanks to the **docx.js** and **unified.js** ecosystems for making this possible.
+A huge thank you to the creators and maintainers of the **docx.js** and **unified.js** ecosystems, which make this library possible.
 
 > ⭐ **Star this repository** if you find it useful!  
-> ❤️ Support our work by [sponsoring](https://github.com/sponsors/mayank1513).
+> ❤️ Support our work by [sponsoring on GitHub](https://github.com/sponsors/mayank1513).
 
 ---