mdast2docx 1.6.0 → 1.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +92 -168
  3. package/dist/index.d.mts +13 -0
  4. package/dist/index.d.ts +13 -1
  5. package/dist/plugins/index.d.mts +7 -0
  6. package/dist/plugins/index.d.ts +7 -7
  7. package/dist/plugins/node/index.d.mts +2 -0
  8. package/dist/plugins/node/index.d.ts +2 -1
  9. package/dist/plugins/node/index.js +1 -35
  10. package/dist/plugins/node/index.mjs +1 -1
  11. package/dist/section.d.mts +1 -0
  12. package/dist/section.d.ts +1 -1
  13. package/dist/utils/cache.d.mts +1 -0
  14. package/dist/utils/cache.d.ts +1 -1
  15. package/dist/utils/index.d.mts +1 -0
  16. package/dist/utils/index.d.ts +1 -1
  17. package/package.json +148 -76
  18. package/dist/chunk-3B7PIKIS.mjs +0 -31
  19. package/dist/chunk-LO72SAXR.mjs +0 -4
  20. package/dist/multipart-parser-RNULNBMT.mjs +0 -2
  21. package/dist/plugins/node/node-image.d.ts +0 -32
  22. package/dist/plugins/node/node-image.js +0 -35
  23. package/dist/plugins/node/node-image.mjs +0 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 turboforge-dev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,222 +1,146 @@
1
- # **MDAST (Markdown Abstract Syntax Tree) to DOCX** <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
2
-
3
- **🚀 A powerful, modular, and extensible Markdown to DOCX converter.**
4
-
5
- <p align="center">
6
- <img src="./banner.svg" alt="logo" style="height: 360px; margin:auto" />
1
+ # mdast2docx <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
2
+
3
+ <p className="flex gap-2">
4
+ <a href="https://github.com/md2docx/md2docx/actions/workflows/ci.yml" rel="noopener noreferrer">
5
+ <img alt="CI" src="https://github.com/md2docx/md2docx/actions/workflows/ci.yml/badge.svg" />
6
+ </a>
7
+ <a href="https://codecov.io/gh/md2docx/md2docx/tree/main/packages/mdast2docx" rel="noopener noreferrer">
8
+ <img alt="codecov" src="https://codecov.io/gh/md2docx/md2docx/graph/badge.svg?flag=mdast2docx" />
9
+ </a>
10
+ <a href="https://npmjs.com/package/mdast2docx" rel="noopener noreferrer">
11
+ <img alt="npm version" src="https://img.shields.io/npm/v/mdast2docx" />
12
+ </a>
13
+ <a href="https://npmjs.com/package/mdast2docx" rel="noopener noreferrer">
14
+ <img alt="npm downloads" src="https://img.shields.io/npm/d18m/mdast2docx" />
15
+ </a>
16
+ <a href="https://npmjs.com/package/mdast2docx" rel="noopener noreferrer">
17
+ <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/mdast2docx" />
18
+ </a>
19
+ <img alt="license" src="https://img.shields.io/npm/l/mdast2docx" />
7
20
  </p>
8
21
 
9
- 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.
10
-
11
- [![Test](https://github.com/md2docx/mdast2docx/actions/workflows/test.yml/badge.svg)](https://github.com/md2docx/mdast2docx/actions/workflows/test.yml)
12
- [![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/md2docx/mdast2docx/maintainability)
13
- [![Code Coverage](https://codecov.io/gh/md2docx/mdast2docx/graph/badge.svg)](https://codecov.io/gh/md2docx/mdast2docx)
14
- [![Version](https://img.shields.io/npm/v/mdast2docx.svg?colorB=green)](https://www.npmjs.com/package/mdast2docx)
15
- [![Downloads](https://img.shields.io/npm/d18m/mdast2docx)](https://www.npmjs.com/package/mdast2docx)
16
- ![Bundle Size](https://img.shields.io/bundlephobia/minzip/mdast2docx)
22
+ > mdast2docx: The complete, all-in-one Markdown Abstract Syntax Tree (MDAST) to Microsoft Word DOCX compiler bundle.
17
23
 
18
24
  ---
19
25
 
20
- ## ✨ Key Features
26
+ ## ✨ Features
21
27
 
22
- - **Modular Architecture**: Keep your bundles small. The core is lightweight, and you can add features like tables, images, or math support via plugins.
23
- - **Comprehensive Markdown Support**: Handles all standard Markdown syntax, including headings, lists, links, code blocks, and more.
24
- - **Client & Server Ready**: Isomorphic design works flawlessly in both Node.js and browser environments.
25
- - **Highly Customizable**: Leverage the full power of `docx.js` to style your document, including headers, footers, margins, and paragraph styles.
26
- - **Scoped Packages**: Install only what you need using `@m2d/*` packages, or grab the all-in-one `mdast2docx` package.
27
-
28
- ---
29
-
30
- ## 🤖 The Generative AI Power-Up
31
-
32
- 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.
33
-
34
- **Workflow:** `AI Output (Markdown)` → `unified/remark (MDAST)` → `mdast2docx` → `Professional DOCX Document`
35
-
36
- - **AI-Generated Reports**: Convert AI-generated summaries and reports into polished DOCX files.
37
- - **Content Export**: Transform AI-generated blogs, articles, and research into an editable DOCX format.
38
- - **Flexible Processing**: Offload document generation to the client for scalability or run it on the server for high-performance batch processing.
28
+ - 📦 **All-in-One Distribution**: Includes `@m2d/core` and the complete official plugin ecosystem (`table`, `list`, `image`, `math`, `mermaid`, `html`, `emoji`).
29
+ - 🤖 **Optimized for Generative AI**: Perfect bridge for converting LLM-generated Markdown into professionally styled Word documents.
30
+ - 📐 **Native Word Structures**: Renders genuine OpenXML tables, native editable equations (`docx.Math`), multi-tier outline numbering, and vector diagrams.
31
+ - 🌐 **Isomorphic Runtimes**: Works identically on both the client (browser downloads via `Blob`) and server (high-throughput Node.js batch generation via `Buffer`).
32
+ - ⚡ **Streamlined Subpaths**: Clean access via `mdast2docx`, `mdast2docx/plugins`, `mdast2docx/section`, and `mdast2docx/utils`.
39
33
 
40
34
  ---
41
35
 
42
36
  ## 📦 Installation
43
37
 
44
- You can install the all-in-one package or select only the scoped packages you need.
38
+ ```bash
39
+ $ pnpm add mdast2docx docx
40
+ ```
45
41
 
46
- ### **Install Everything at Once**
42
+ **_or_**
47
43
 
48
44
  ```bash
49
- pnpm add mdast2docx
45
+ $ npm install mdast2docx docx
50
46
  ```
51
47
 
52
- ### **Or Install Only What You Need**
48
+ **_or_**
53
49
 
54
50
  ```bash
55
- pnpm add @m2d/core @m2d/image @m2d/table # and other plugins
51
+ $ yarn add mdast2docx docx
56
52
  ```
57
53
 
58
54
  ---
59
55
 
60
- ## 🚀 Usage
61
-
62
- 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.
63
-
64
- ### **Basic Example**
65
-
66
- This example uses the core `toDocx` function to convert an MDAST object into a DOCX file and trigger a download in the browser.
56
+ ## 🚀 Quick Start
67
57
 
68
58
  ```typescript
69
59
  import { toDocx } from "mdast2docx";
70
- import { unified } from "unified";
60
+ import {
61
+ htmlPlugin,
62
+ imagePlugin,
63
+ listPlugin,
64
+ mathPlugin,
65
+ mermaidPlugin,
66
+ tablePlugin,
67
+ } from "mdast2docx/plugins";
68
+ import remarkGfm from "remark-gfm";
69
+ import remarkMath from "remark-math";
71
70
  import remarkParse from "remark-parse";
71
+ import { unified } from "unified";
72
72
 
73
- // 1. Your Markdown content
74
73
  const markdown = `
75
- # Sample Document
76
- This is a paragraph with **bold** and _italic_ text.
74
+ # Executive Summary
77
75
 
78
- > A blockquote.
76
+ This document was generated automatically from **Markdown**.
79
77
 
80
- * List Item 1
81
- * List Item 2
78
+ ## Key Metrics
82
79
 
83
- [Visit our website](https://example.com)
84
- `;
85
-
86
- // 2. Parse Markdown to MDAST
87
- const mdast = unified().use(remarkParse).parse(markdown);
88
-
89
- // 3. Convert MDAST to DOCX and download
90
- async function generateDocx() {
91
- const docxBlob = await toDocx(mdast);
92
-
93
- // Create a download link
94
- const url = URL.createObjectURL(docxBlob as Blob);
95
- const link = document.createElement("a");
96
- link.href = url;
97
- link.download = "document.docx";
98
- document.body.appendChild(link);
99
- link.click();
100
- document.body.removeChild(link);
101
- URL.revokeObjectURL(url);
102
- }
103
-
104
- generateDocx();
105
- ```
106
-
107
- ---
80
+ | Metric | Target | Actual |
81
+ | :----- | :----: | -----: |
82
+ | Latency | < 50ms | 28ms |
83
+ | Uptime | 99.9% | 99.99% |
108
84
 
109
- ## 🔌 Plugins
85
+ ## System Flowchart
110
86
 
111
- The core library is intentionally lean. Use plugins to add support for features like images, tables, math equations, and more.
87
+ \`\`\`mermaid
88
+ graph LR
89
+ Ingest --> Process --> Storage
90
+ \`\`\`
112
91
 
113
- ### **Example: Using Plugins**
114
-
115
- 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.
116
-
117
- ```typescript
118
- import { toDocx } from "@m2d/core";
119
- import { imagePlugin } from "@m2d/image";
120
- import { tablePlugin } from "@m2d/table";
121
- import { mathPlugin } from "@m2d/math";
122
- import { unified } from "unified";
123
- import remarkParse from "remark-parse";
124
- import remarkGfm from "remark-gfm"; // For table support
125
- import remarkMath from "remark-math"; // For math support
126
-
127
- const markdownWithFeatures = `
128
- An image: ![alt text](https://via.placeholder.com/150)
129
-
130
- | Header 1 | Header 2 |
131
- |----------|----------|
132
- | Cell 1 | Cell 2 |
133
-
134
- A math equation: $E = mc^2$
92
+ Inline formula: $E = mc^2$
135
93
  `;
136
94
 
95
+ // 1. Parse markdown with unified
137
96
  const mdast = unified()
138
97
  .use(remarkParse)
139
- .use(remarkGfm) // Enable GFM for tables
140
- .use(remarkMath) // Enable math syntax
141
- .parse(markdownWithFeatures);
142
-
143
- (async () => {
144
- const docxBlob = await toDocx(
145
- mdast,
146
- {}, // docxProps
147
- {
148
- // Pass plugins in sectionProps
149
- plugins: [imagePlugin(), tablePlugin(), mathPlugin()],
150
- }
151
- );
152
- // ... download logic ...
153
- })();
98
+ .use(remarkGfm)
99
+ .use(remarkMath)
100
+ .parse(markdown);
101
+
102
+ // 2. Compile to Word DOCX with bundled plugins
103
+ const docxBlob = await toDocx(mdast, {}, {
104
+ plugins: [
105
+ htmlPlugin(),
106
+ mermaidPlugin(),
107
+ imagePlugin(),
108
+ tablePlugin(),
109
+ listPlugin(),
110
+ mathPlugin(),
111
+ ],
112
+ });
154
113
  ```
155
114
 
156
115
  ---
157
116
 
158
- ## 📜 API Reference
159
-
160
- ### **`toDocx(astInputs, docxProps?, sectionProps?, outputType?)`**
161
-
162
- Converts one or more MDAST trees into a DOCX document.
163
-
164
- | Parameter | Type | Description |
165
- | :------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
166
- | `astInputs` | `Root` | `{ ast: Root; props?: ISectionProps }[]` | A single MDAST root node or an array of nodes, each with optional section properties. |
167
- | `docxProps` | `IDocxProps` | Optional. Global document properties like title, author, and styles. See [docx.js docs](https://docx.js.org/#/usage/document). |
168
- | `sectionProps` | `ISectionProps` | Optional. Default properties for document sections, like margins and plugins. See [docx.js docs](https://docx.js.org/#/usage/sections). |
169
- | `outputType` | `"blob"` | `"buffer"` | `"base64"` | Optional. The output format. Defaults to `"blob"` in browsers and `"buffer"` in Node.js. |
170
-
171
- **Returns:** `Promise<Blob | Buffer | string>` — A promise that resolves with the generated DOCX document in the specified format.
172
-
173
- ---
174
-
175
- ## ✅ Supported Markdown Elements
176
-
177
- | Feature | Supported | Plugin Required |
178
- | :--------------------- | :-------: | :-------------- |
179
- | Headings (`# H1`) | ✅ | **No** |
180
- | Paragraphs | ✅ | **No** |
181
- | Bold & Italic | ✅ | **No** |
182
- | Blockquotes | ✅ | **No** |
183
- | Links | ✅ | **No** |
184
- | Code Blocks | ✅ | **No** |
185
- | Footnotes | ✅ | **No** |
186
- | Unordered Lists | ✅ | **No** |
187
- | Images `![alt](url)` | ✅ | `@m2d/image` |
188
- | Tables (GFM) | ✅ | `@m2d/table` |
189
- | Ordered Lists | ✅ | `@m2d/list` |
190
- | Math Equations (LaTeX) | ✅ | `@m2d/math` |
191
- | Raw HTML | ✅ | `@m2d/html` |
117
+ ## 🔌 Bundled Plugins
192
118
 
193
- ---
194
-
195
- ## 🤝 Contributing
196
-
197
- We welcome contributions\! Please feel free to fork the repository, create a feature branch, and open a pull request.
119
+ The `mdast2docx/plugins` subpath provides instant access to all official plugins:
198
120
 
199
- 1. **Fork** the repository.
200
- 2. **Create a feature branch** (`git checkout -b feature/your-new-feature`).
201
- 3. **Commit your changes** (`git commit -m "Add a new feature"`).
202
- 4. **Push to the branch** (`git push origin feature/your-new-feature`).
203
- 5. **Open a Pull Request**. 🚀
121
+ | Plugin | Source Package | Capability |
122
+ | :--- | :--- | :--- |
123
+ | `tablePlugin` | [`@m2d/table`](https://npmjs.com/package/@m2d/table) | Rich borders, repeating headers, cell fills, and column alignment |
124
+ | `listPlugin` | [`@m2d/list`](https://npmjs.com/package/@m2d/list) | Hierarchical decimal numbering (`1.1.1`) and multi-tier bullet glyphs |
125
+ | `imagePlugin` | [`@m2d/image`](https://npmjs.com/package/@m2d/image) | SVG and URL image resolution, rasterization, and dimensions |
126
+ | `mermaidPlugin` | [`@m2d/mermaid`](https://npmjs.com/package/@m2d/mermaid) | Client-side Mermaid diagrams with auto-healing syntax |
127
+ | `mathPlugin` | [`@m2d/math`](https://npmjs.com/package/@m2d/math) | LaTeX math translated to native editable Word MathML equations |
128
+ | `htmlPlugin` | [`@m2d/html`](https://npmjs.com/package/@m2d/html) | Embedded HTML tag parsing and inline CSS styles |
129
+ | `emojiPlugin` | [`@m2d/emoji`](https://npmjs.com/package/@m2d/emoji) | GitHub emoji shortcodes to Unicode characters |
204
130
 
205
131
  ---
206
132
 
207
- ## 📄 License
133
+ ## 📚 Deep Dive Guides
208
134
 
209
- This project is licensed under the **MPL-2.0**. See the [LICENSE](./LICENSE) file for details.
135
+ - 📦 **[Umbrella Architecture & Package Structure Guide](./docs/umbrella-architecture.mdx)**: Subpath exports, ecosystem structure, and choosing between umbrella vs scoped packages.
136
+ - 🚀 **[Production Best Practices & Migration Guide](./docs/migration-and-best-practices.mdx)**: AI pipelines, server vs browser deployment, table layouts, and v1.x migration.
210
137
 
211
138
  ---
212
139
 
213
- ## 🙌 Acknowledgments
140
+ ## License
214
141
 
215
- A huge thank you to the creators and maintainers of the **docx.js** and **unified.js** ecosystems, which make this library possible.
142
+ This library is licensed under the MIT open-source license.
216
143
 
217
- > ⭐ **Star this repository** if you find it useful!
218
- > ❤️ Support our work by [sponsoring on GitHub](https://github.com/sponsors/mayank1513).
219
-
220
- ---
144
+ <hr />
221
145
 
222
- <p align="center">Made with 💖 by <a href="https://mayank-chaudhari.vercel.app" target="_blank">Mayank Kumar Chaudhari</a></p>
146
+ <p align="center">with 💖 by <a href="https://mayankchaudhari.com" target="_blank">Mayank Kumar Chaudhari</a></p>
package/dist/index.d.mts ADDED
@@ -0,0 +1,13 @@
1
+ export * from '@m2d/core';
2
+ import '@m2d/emoji';
3
+ import '@m2d/html';
4
+ import '@m2d/image';
5
+ import '@m2d/list';
6
+ import '@m2d/math';
7
+ import '@m2d/mermaid';
8
+ import '@m2d/table';
9
+ import '@m2d/image-node';
10
+ import '@m2d/mermaid-node';
11
+ import '@m2d/core/section';
12
+ import '@m2d/core/cache';
13
+ import '@m2d/core/utils';
package/dist/index.d.ts CHANGED
@@ -1 +1,13 @@
1
- export * from "@m2d/core";
1
+ export * from '@m2d/core';
2
+ import '@m2d/emoji';
3
+ import '@m2d/html';
4
+ import '@m2d/image';
5
+ import '@m2d/list';
6
+ import '@m2d/math';
7
+ import '@m2d/mermaid';
8
+ import '@m2d/table';
9
+ import '@m2d/image-node';
10
+ import '@m2d/mermaid-node';
11
+ import '@m2d/core/section';
12
+ import '@m2d/core/cache';
13
+ import '@m2d/core/utils';
package/dist/plugins/index.d.mts ADDED
@@ -0,0 +1,7 @@
1
+ export * from '@m2d/emoji';
2
+ export * from '@m2d/html';
3
+ export * from '@m2d/image';
4
+ export * from '@m2d/list';
5
+ export * from '@m2d/math';
6
+ export * from '@m2d/mermaid';
7
+ export * from '@m2d/table';
package/dist/plugins/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- export * from "@m2d/emoji";
2
- export * from "@m2d/html";
3
- export * from "@m2d/image";
4
- export * from "@m2d/list";
5
- export * from "@m2d/math";
6
- export * from "@m2d/mermaid";
7
- export * from "@m2d/table";
1
+ export * from '@m2d/emoji';
2
+ export * from '@m2d/html';
3
+ export * from '@m2d/image';
4
+ export * from '@m2d/list';
5
+ export * from '@m2d/math';
6
+ export * from '@m2d/mermaid';
7
+ export * from '@m2d/table';
package/dist/plugins/node/index.d.mts ADDED
@@ -0,0 +1,2 @@
1
+ export * from '@m2d/image-node';
2
+ export * from '@m2d/mermaid-node';
package/dist/plugins/node/index.d.ts CHANGED
@@ -1 +1,2 @@
1
- export * from "./node-image";
1
+ export * from '@m2d/image-node';
2
+ export * from '@m2d/mermaid-node';