@m2d/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

$ 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