@mdast2docx/html

@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

Made with 💖 by Mayank Kumar Chaudhari