mdast2docx 1.4.2 → 1.5.1

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 (12) hide show
  1. package/README.md +128 -148
  2. package/dist/chunk-CWUY2JLF.mjs +4 -0
  3. package/dist/plugins/index.d.ts +3 -3
  4. package/dist/plugins/index.js +1 -1
  5. package/dist/plugins/index.mjs +1 -1
  6. package/dist/plugins/node/index.js +8 -8
  7. package/dist/plugins/node/index.mjs +1 -1
  8. package/dist/plugins/node/node-image.d.ts +3 -2
  9. package/dist/plugins/node/node-image.js +8 -8
  10. package/dist/plugins/node/node-image.mjs +1 -1
  11. package/package.json +16 -64
  12. package/dist/chunk-2EAXVYAR.mjs +0 -4
package/README.md CHANGED
@@ -1,58 +1,47 @@
1
1
  # **MDAST (Markdown Abstract Syntax Tree) to DOCX** <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
2
2
 
3
- 🚀 **Effortlessly convert Markdown Abstract Syntax Trees (MDAST) to DOCX.**
3
+ **🚀 A powerful, modular, and extensible Markdown to DOCX converter.**
4
4
 
5
- [![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)
5
+ <p align="center">
6
+ <img src="./banner.svg" alt="logo" style="height: 360px; margin:auto" />
7
+ </p>
6
8
 
7
- ---
8
-
9
- ## **✨ Features**
10
-
11
- ✅ **MDAST to DOCX conversion** — Supports standard Markdown elements
12
- ✅ **Footnotes handling** — Converts Markdown footnotes to DOCX format
13
- ✅ **Tables support** — Converts Markdown tables into DOCX tables
14
- ✅ **Hyperlink support** — External and internal hyperlinks are now fully functional
15
- ✅ **New Plugin Architecture** — Extend and customize DOCX output with plugins
16
- ✅ **Customizable image handling** — Images are now supported via `@m2d/image` plugin
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.
17
10
 
18
- > **Note:** Images are no longer supported by default. To enable image support, use the image plugin from `@m2d/image` or `mdast2docx/plugins` explicitly.
19
- > This change helps us keep the library lean and extensible by community via plugins.
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)
20
17
 
21
18
  ---
22
19
 
23
- ## **🚀 Relevance to Generative AI**
24
-
25
- <details open>
26
- <summary>
27
- <i>Converts markdown content/artifacts generated by Generative AI to docx for further processing/record-keeping/sharing.</i>
28
- </summary>
29
-
30
- 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.
31
-
32
- ### **How It Works**
20
+ ## ✨ Key Features
33
21
 
34
- 1. **AI tools generate content in Markdown**.
35
- 2. **Unified.js & Remark Ecosystem** convert Markdown into **Markdown Abstract Syntax Tree (MDAST)**.
36
- 3. **MDAST to DOCX** processes this structure and exports a **well-formatted DOCX document**.
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.
37
27
 
38
- ### **Use Cases**
39
-
40
- - **AI-Generated Reports** – Convert AI-generated Markdown reports into polished DOCX files.
41
- - **AI-Powered Content Export** – Transform AI-generated blogs, research papers, and structured content into a DOCX format for easy sharing and editing.
42
- - **Client & Server Flexibility** – Works both in **browser-based AI tools** and **high-performance server environments**.
28
+ ---
43
29
 
44
- ### **✅ Benefits**
30
+ ## 🤖 The Generative AI Power-Up
45
31
 
46
- - **Works on both Client & Server** – Choose to **offload processing to the client** for better scalability or **run it on the server** for batch conversions.
47
- - **Optimized & Extensible** – Use **only the plugins you need**, keeping your AI workflows lightweight.
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.
48
33
 
49
- By integrating **MDAST to DOCX**, AI applications can **seamlessly export Markdown-based content into DOCX**, making it more accessible, editable, and shareable. 🚀
34
+ **Workflow:** `AI Output (Markdown)` → `unified/remark (MDAST)` → `mdast2docx` → `Professional DOCX Document`
50
35
 
51
- </details>
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.
52
39
 
53
40
  ---
54
41
 
55
- ## **📦 Installation**
42
+ ## 📦 Installation
43
+
44
+ You can install the all-in-one package or select only the scoped packages you need.
56
45
 
57
46
  ### **Install Everything at Once**
58
47
 
@@ -60,182 +49,173 @@ By integrating **MDAST to DOCX**, AI applications can **seamlessly export Markdo
60
49
  pnpm add mdast2docx
61
50
  ```
62
51
 
63
- ### **Or Install Only What You Need (Scoped Packages)**
52
+ ### **Or Install Only What You Need**
64
53
 
65
54
  ```bash
66
- pnpm add @m2d/core @m2d/html @m2d/image @m2d/math @m2d/table @m2d/list @m2d/mdast
55
+ pnpm add @m2d/core @m2d/image @m2d/table # and other plugins
67
56
  ```
68
57
 
69
58
  ---
70
59
 
71
- ## **🚀 Usage**
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.
72
63
 
73
64
  ### **Basic Example**
74
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.
67
+
75
68
  ```typescript
76
69
  import { toDocx } from "mdast2docx";
77
70
  import { unified } from "unified";
78
71
  import remarkParse from "remark-parse";
79
- import remarkMmd from "remark-mmd"; // Assumed MMD plugin
80
72
 
73
+ // 1. Your Markdown content
81
74
  const markdown = `
82
- # Sample Document
83
- This is a **bold** text and _italic_ text.
75
+ # Sample Document
76
+ This is a paragraph with **bold** and _italic_ text.
84
77
 
85
- > A blockquote example
78
+ > A blockquote.
86
79
 
87
- - List Item 1
88
- - List Item 2
80
+ * List Item 1
81
+ * List Item 2
89
82
 
90
- [Click Here](https://example.com)
91
-
92
- This is a footnote reference[^1].
93
-
94
- [^1]: This is the footnote content.
83
+ [Visit our website](https://example.com)
95
84
  `;
96
85
 
97
- const mdast = unified().use(remarkParse).use(remarkMmd).parse(markdown);
86
+ // 2. Parse Markdown to MDAST
87
+ const mdast = unified().use(remarkParse).parse(markdown);
98
88
 
99
- (async () => {
100
- const docxBlob = await toDocx(mdast, { title: "My Document" }, {});
89
+ // 3. Convert MDAST to DOCX and download
90
+ async function generateDocx() {
91
+ const docxBlob = await toDocx(mdast);
92
+
93
+ // Create a download link
101
94
  const url = URL.createObjectURL(docxBlob as Blob);
102
95
  const link = document.createElement("a");
103
96
  link.href = url;
104
97
  link.download = "document.docx";
98
+ document.body.appendChild(link);
105
99
  link.click();
100
+ document.body.removeChild(link);
106
101
  URL.revokeObjectURL(url);
107
- })();
108
- ```
109
-
110
- ---
111
-
112
- ## **📜 API Reference**
113
-
114
- ### **`toDocx(astInputs, docxProps, defaultSectionProps, outputType?)`**
115
-
116
- | Parameter | Type | Description |
117
- | ------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
118
- | `astInputs` | `Root` \| `{ ast: Root; props?: ISectionProps }[]` | Single or multiple MDAST trees with optional section properties. |
119
- | `docxProps` | `IDocxProps` | General document properties (title, styles, metadata). |
120
- | `defaultSectionProps` | `ISectionProps` | Default properties for document sections. |
121
- | `outputType` _(optional)_ | `"blob"` (default) \| `"buffer"` \| `"base64"` | Format of the generated DOCX document. |
102
+ }
122
103
 
123
- 📌 **Returns:** A `Promise` resolving to a DOCX document in the chosen format.
104
+ generateDocx();
105
+ ```
124
106
 
125
107
  ---
126
108
 
127
- ## **📜 Supported Markdown Elements**
128
-
129
- | Markdown Syntax | Supported in DOCX |
130
- | ---------------------------------- | ------------------------------------- |
131
- | Headings `# H1` to `###### H6` | ✅ |
132
- | Paragraphs | ✅ |
133
- | Bold `**text**` & Italics `_text_` | ✅ |
134
- | Blockquotes `> quote` | ✅ |
135
- | Lists (ordered & unordered) | ✅ _(ordered lists via `listPlugin`)_ |
136
- | Links `[text](url)` | ✅ |
137
- | Images `![alt](url)` | ✅ _(via `imagePlugin`)_ |
138
- | Code Blocks `` `code` `` | ✅ |
139
- | Footnotes `[^1]` | ✅ |
140
- | Tables | ✅ _(via `tablePlugin`)_ |
141
- | Hyperlinks (external & internal) | ✅ |
142
- | Latex Math | ✅ _(via `mathPlugin`)_ |
143
- | HTML Tags | ✅ _(via `htmlPlugin`)_ |
144
-
145
- ---
109
+ ## 🔌 Plugins
146
110
 
147
- ## **🔧 Configuration**
111
+ The core library is intentionally lean. Use plugins to add support for features like images, tables, math equations, and more.
148
112
 
149
- You can customize the DOCX output using `ISectionProps` and `IDocxProps`.
113
+ ### **Example: Using Plugins**
150
114
 
151
- ### **Example: Customizing Styles**
152
-
153
- ```typescript
154
- const docxProps = {
155
- title: "Styled Document",
156
- author: "John Doe",
157
- };
158
-
159
- const sectionProps = {
160
- page: { margin: { top: 1000, bottom: 1000, left: 1200, right: 1200 } },
161
- };
162
-
163
- const docxBlob = await toDocx(mdast, docxProps, sectionProps);
164
- ```
165
-
166
- ### **Use Plugins**
167
-
168
- Plugins allow extending functionality like adding image or table support.
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.
169
116
 
170
117
  ```typescript
171
118
  import { toDocx } from "@m2d/core";
172
119
  import { imagePlugin } from "@m2d/image";
173
120
  import { tablePlugin } from "@m2d/table";
174
- import { listPlugin } from "@m2d/list";
175
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$
135
+ `;
136
+
137
+ const mdast = unified()
138
+ .use(remarkParse)
139
+ .use(remarkGfm) // Enable GFM for tables
140
+ .use(remarkMath) // Enable math syntax
141
+ .parse(markdownWithFeatures);
176
142
 
177
- const downloadDocx = () => {
178
- toDocx(
143
+ (async () => {
144
+ const docxBlob = await toDocx(
179
145
  mdast,
180
- {},
181
- { plugins: [imagePlugin(), tablePlugin(), listPlugin(), mathPlugin()] },
182
- "blob",
183
- ).then(blob => {
184
- const url = URL.createObjectURL(blob as Blob);
185
- const link = document.createElement("a");
186
- link.href = url;
187
- link.download = "my-document.docx";
188
- link.click();
189
- URL.revokeObjectURL(url);
190
- });
191
- };
146
+ {}, // docxProps
147
+ {
148
+ // Pass plugins in sectionProps
149
+ plugins: [imagePlugin(), tablePlugin(), mathPlugin()],
150
+ }
151
+ );
152
+ // ... download logic ...
153
+ })();
192
154
  ```
193
155
 
194
- 📖 **More details:**
156
+ ---
195
157
 
196
- - [DOCX.js Document Properties](https://docx.js.org/#/usage/document)
197
- - [DOCX.js Section Options](https://docx.js.org/#/usage/sections)
158
+ ## 📜 API Reference
198
159
 
199
- ---
160
+ ### **`toDocx(astInputs, docxProps?, sectionProps?, outputType?)`**
200
161
 
201
- ## **🧠 Relevance in Generative AI**
162
+ Converts one or more MDAST trees into a DOCX document.
202
163
 
203
- 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.
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. |
204
170
 
205
- - Supports both **client-side** and **server-side** usage
206
- - Enables **offloading document generation** to users' browsers or running high-performance server renderers
207
- - Combine it with `unified` and `remark` to parse Markdown into MDAST, and then convert to DOCX seamlessly
171
+ **Returns:** `Promise<Blob | Buffer | string>` — A promise that resolves with the generated DOCX document in the specified format.
208
172
 
209
173
  ---
210
174
 
211
- ## **📝 Contributing**
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` |
212
192
 
213
- We welcome contributions! To get started:
193
+ ---
214
194
 
215
- 1. **Fork** the repository
216
- 2. **Create a feature branch** (`git checkout -b feature-new`)
217
- 3. **Commit your changes** (`git commit -m "Add new feature"`)
218
- 4. **Push to GitHub** (`git push origin feature-new`)
219
- 5. **Open a Pull Request** 🚀
195
+ ## 🤝 Contributing
220
196
 
221
- ### **Extend Functionality with Plugins**
197
+ We welcome contributions\! Please feel free to fork the repository, create a feature branch, and open a pull request.
222
198
 
223
- 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.
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**. 🚀
224
204
 
225
205
  ---
226
206
 
227
- ## **📄 License**
207
+ ## 📄 License
228
208
 
229
- This project is **licensed under MPL-2.0**. See the [LICENSE](./LICENSE) file for details.
209
+ This project is licensed under the **MPL-2.0**. See the [LICENSE](./LICENSE) file for details.
230
210
 
231
211
  ---
232
212
 
233
- ## **🙌 Acknowledgments**
213
+ ## 🙌 Acknowledgments
234
214
 
235
- Thanks to the **docx.js** and **unified.js** ecosystems for making this possible.
215
+ A huge thank you to the creators and maintainers of the **docx.js** and **unified.js** ecosystems, which make this library possible.
236
216
 
237
217
  > ⭐ **Star this repository** if you find it useful!
238
- > ❤️ Support our work by [sponsoring](https://github.com/sponsors/mayank1513).
218
+ > ❤️ Support our work by [sponsoring on GitHub](https://github.com/sponsors/mayank1513).
239
219
 
240
220
  ---
241
221