> @m2d/html: HTML to Extended MDAST preprocessing plugin for `@m2d/core`. Transforms raw embedded HTML strings into structured MDAST nodes for rich Word DOCX conversion.
---
## ✨ Features
- 🌐 **Embedded HTML Parsing**: Converts raw HTML tags inside Markdown into structured MDAST nodes, enabling HTML-to-Word generation.
- 🎨 **Inline CSS Resolution**: Extracts and translates inline CSS (`color`, `background-color`, `text-align`, `font-weight`, `font-size`, `borders`) into native Word OpenXML styling.
- 🧩 **Deep Ecosystem Integration**: Upgrades raw ``, `
`, and list tags so that downstream plugins (`@m2d/image`, `@m2d/table`, `@m2d/list`) can process them seamlessly.
- ☑️ **Interactive Elements**: Translates `` elements into clean Unicode checkbox representations (`☑` / `☐`).
- ⚡ **Lightweight DOM Parsing**: Fast, robust stack-based parsing that pairs closing tags across sibling Markdown nodes without mangling surrounding content.
---
## 📦 Installation
> [!TIP]
> **This package (@mdast2docx/html) is an official alias of [@m2d/html](https://npmjs.com/package/@m2d/html).**
Why does this exist?
We provide this package to offer shorter import paths and improved discoverability. While both packages provide identical functionality, **@m2d/html** is the primary source of truth.
Which one should I use?
* **Use @mdast2docx/html** if you prefer the shorter name or specific branding or ESM Only.
* **Use @m2d/html** for the most stable long-term reference and standard alignment.
| Feature | @m2d/html | @mdast2docx/html |
| --- | --- | --- |
| **Source Code** | ✅ Primary | 🔗 Proxy |
| **Updates** | Immediate | Synchronized (Immediately) |
| **Bundle Size** | 100% | 100% (Zero overhead) |
| **Format** | ESM + CJS | ESM Only |
| **Maintenance** | ✅ Primary | 🔗 Proxy (inherits) |
| **Security** | ✅ Primary | 🔗 Proxy (inherits) |
Maintenance & Support
> **Security:** Security audits are performed on the canonical package; this alias inherits all security patches automatically.
---
```bash
$ pnpm add @m2d/html @m2d/core docx
```
**_or_**
```bash
$ npm install @m2d/html @m2d/core docx
```
**_or_**
```bash
$ yarn add @m2d/html @m2d/core docx
```
---
## 🚀 Quick Start
```typescript
import { toDocx } from "@m2d/core";
import { htmlPlugin } from "@m2d/html";
import { imagePlugin } from "@m2d/image";
import { tablePlugin } from "@m2d/table";
import remarkParse from "remark-parse";
import { unified } from "unified";
const markdown = `
# Project Report
Important Alert:
The schedule has moved forward by 2 weeks.
Milestone
Target
Alpha Release
November 1st
`;
const mdast = unified().use(remarkParse).parse(markdown);
const docxBlob = await toDocx(mdast, {}, {
plugins: [
htmlPlugin(), // 1. MUST BE REGISTERED FIRST: Converts raw HTML to MDAST nodes
tablePlugin(), // 2. Formats table nodes generated by htmlPlugin
imagePlugin(), // 3. Rasterizes image nodes generated by htmlPlugin
],
});
```
> ⚠️ **Important Pipeline Order**: Always register `htmlPlugin()` **at the beginning** of your plugins array. It executes during the `preprocess` phase to generate the MDAST nodes that subsequent plugins rely upon.
### Standalone Utilities (`@m2d/html/utils`)
```typescript
import { standardizeColor, type DocumentLike } from "@m2d/html/utils";
// Normalizes CSS colors ('#ff0000', 'red', 'rgb(...)') into DOCX 6-digit hex ('ff0000')
const hexColor = standardizeColor("red"); // "ff0000"
```
---
## 📚 Deep Dive Guides
- 🔄 **[AST Transformation & Pipeline Order Guide](./docs/ast-transformation-and-pipeline-order.mdx)**: Tag-matching stack architecture and execution sequence in `@m2d/core`.
- 🎨 **[Supported Elements & Inline CSS Guide](./docs/supported-elements-and-inline-css.mdx)**: Supported HTML elements, inline style mappings, and known limitations.
---
## License
This library is licensed under the MIT open-source license.
