@mdast2docx/html

@m2d/html

@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 <img>, <table>, and list tags so that downstream plugins (@m2d/image, @m2d/table, @m2d/list) can process them seamlessly.
• Interactive Elements: Translates <input type="checkbox"> 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

This package (@mdast2docx/html) is an official alias of @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.

---

$ pnpm add @m2d/html @m2d/core docx

or

$ npm install @m2d/html @m2d/core docx

or

$ yarn add @m2d/html @m2d/core docx

---

Quick Start

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

<span style="color: #2563EB; font-weight: bold;">Important Alert:</span>
The schedule has moved forward by 2 weeks.

<table>
  <tr>
    <th style="background-color: #1E293B; color: #FFFFFF;">Milestone</th>
    <th style="background-color: #1E293B; color: #FFFFFF;">Target</th>
  </tr>
  <tr>
    <td>Alpha Release</td>
    <td>November 1st</td>
  </tr>
</table>
`;

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)

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: Tag-matching stack architecture and execution sequence in @m2d/core.
• Supported Elements & Inline CSS Guide: Supported HTML elements, inline style mappings, and known limitations.

---

License

This library is licensed under the MIT open-source license.

---

with by Mayank Kumar Chaudhari