@m2d/html

Parses embedded HTML into extended MDAST nodes to unlock full HTML-to-DOCX conversion support.

📦 Installation

npm install @m2d/html

pnpm add @m2d/html

yarn add @m2d/html

🚀 Overview

The @m2d/html plugin for mdast2docx enables the parsing and transformation of embedded raw HTML inside Markdown into extended MDAST. This unlocks the ability to support features like images, tables, checkboxes, styles, and more — using HTML tags directly inside your Markdown documents.

⚠️ Important

This plugin must be registered early in the plugin pipeline.
It transforms raw HTML into extended MDAST nodes, which are then handled by other @m2d/* plugins (such as @m2d/image, @m2d/table, etc).
If used after other plugins, the HTML content, e.g, images, tables, or lists may be ignored or lost in the DOCX output.

🛠️ Usage

import { htmlPlugin } from "@m2d/html";

const plugins = [
  htmlPlugin(), // ✅ Must come first
  imagePlugin(),
  tablePlugin(),
];

🧩 How It Works

1. Parses raw embedded HTML using the DOM.
2. Converts DOM nodes to extended MDAST nodes.
3. Other @m2d/* plugins or the @m2d/core package consume these extended nodes to generate DOCX output.

This plugin enriches the AST to enable other plugins and core engine to convert it to docx.

✅ Supported Elements

| HTML Element | MDAST Node | Notes | | ------------------------- | ----------------- | ------------------------------------ | | <img> | image | Supports styles and attributes | | <br> | break | Line breaks | | <strong>, <b> | strong | Bold text | | <em>, <i> | emphasis | Italics | | <del>, <s> | delete | Strike-through | | <a> | link | Hyperlinks | | <table> | table, row | Basic tables supported | | <input type="checkbox"> | checkbox | Readonly checkboxes | | <hr> | thematicBreak | Horizontal line | | <blockquote> | blockquote | Blockquotes | | Others | paragraph, etc. | Styled or inline nodes with rich AST |

🎨 Style Support

• text-align, color, background-color
• font-weight, font-style, text-decoration
• text-transform
• border, border-left, etc.
• display: inline-block and similar behaviors

⚠️ Limitations

• External <style> tags or CSS files are not supported.
• Complex or deeply nested HTML may be simplified.
• Table rowSpan and colSpan are not yet supported.
• Script tags and non-visual elements are ignored.

🧪 Production Ready

While this plugin was originally experimental, it is now stable and production-ready.
It powers the rich HTML support in mdast2docx, including checkboxes, tables, and styled images.

🧵 Contributions, ideas, and feedback are welcome! Open an issue or PR anytime.

🔌 Related Plugins/Packages

| Plugin | Purpose | | ---------------------------------------------------- | -------------------------------------- | | @m2d/core | Converts extended MDAST to DOCX | | @m2d/image | Renders image nodes to DOCX | | @m2d/table | Renders table nodes to DOCX | | @m2d/list | Enhanced list support (tasks, bullets) |

⭐ Support Us

If you find this useful:

• ⭐ Star mdast2docx on GitHub
• ❤️ Consider sponsoring

🧾 License

MIT © Mayank Chaudhari