Merge pull request #1 from md2docx/html

Html

Author: mayank1513

.github/workflows/manual-publish.yml

@@ -33,8 +33,8 @@ jobs:
         working-directory: ./lib
       - name: clean up working directory
         run: git status && git clean -f -d && git status
-      # - name: Copy Readme file
-      # run: cp ./README.md ./lib # todo: uncomment this line while rebranding
+      - name: Copy Readme file
+        run: cp ./README.md ./lib # todo: uncomment this line while rebranding
       - name: Apply changesets, publish and create release, branches and tags
         run: node ./scripts/manual-publish.js
         env:

.github/workflows/publish.yml

@@ -35,8 +35,8 @@ jobs:
       - name: Test
         run: pnpm test
         working-directory: ./lib
-      # - name: Copy Readme file
-      # run: cp ./README.md ./lib # will be uncommented while rebranding
+      - name: Copy Readme file
+        run: cp ./README.md ./lib # will be uncommented while rebranding
       - name: Apply changesets, publish and create release, branches and tags
         run: node ./scripts/publish.js
         env:

.tkb

@@ -1,6 +1,46 @@
 {
   "scope": "Workspace",
   "tasks": {
+    "G-1H47JpSI69kav1qZ-kp": {
+      "id": "G-1H47JpSI69kav1qZ-kp",
+      "description": "Star [this repository](https://github.com/md2docx/md2docx-plugin-template/) for easy access and to show your support",
+      "columnId": "column-todo"
+    },
+    "RX4J5v4y5IOe_ucf8pMRT": {
+      "id": "RX4J5v4y5IOe_ucf8pMRT",
+      "description": "🌟 Enable [private vulnerability reporting](https://github.com/md2docx/html/security) (For public repo - do this after updating visibility to public)",
+      "columnId": "column-todo"
+    },
+    "EdPbrbJLllUHfZmCS80f7": {
+      "id": "EdPbrbJLllUHfZmCS80f7",
+      "description": "Set up `CodeCov`\n  - Visit Codecov and set up your repo\n  - Create [repository secret]((https://github.com/md2docx/html/settings/secrets/actions)) for `CODECOV_TOKEN`",
+      "columnId": "column-todo"
+    },
+    "MLLUsAhCKaKxvEXFY0HSq": {
+      "id": "MLLUsAhCKaKxvEXFY0HSq",
+      "description": "Set up `CodeClimate`\n  - Visit CodeClimate and set up your repo\n  - Create [repository secret]((https://github.com/md2docx/html/settings/secrets/actions)) for `CC_TEST_REPORTER_ID`\n  - Add `*.test.*` to ignore patterns on the website\n  - Update Code Climate badge",
+      "columnId": "column-todo"
+    },
+    "gMYfaAh2RABMP8uZRQgNx": {
+      "id": "gMYfaAh2RABMP8uZRQgNx",
+      "description": "Add `NPM_AUTH_TOKEN` to repository secrets to automate package publishing\n  - Log in to your [`npm` account](https://www.npmjs.com/login) and create an automation token\n  - Create a new repository secret `NPM_AUTH_TOKEN`",
+      "columnId": "column-todo"
+    },
+    "dC7QDBLH8BmHUfaYmIt81": {
+      "id": "dC7QDBLH8BmHUfaYmIt81",
+      "description": "(Optional) Add Repo Stats by visiting and setting up [repobeats](https://repobeats.axiom.co/)",
+      "columnId": "column-todo"
+    },
+    "P_NrSJQ8m91Odgz8E1fS6": {
+      "id": "P_NrSJQ8m91Odgz8E1fS6",
+      "description": "Create your library and update examples",
+      "columnId": "column-todo"
+    },
+    "1dRWJhy45E1Rq5wZAmPHt": {
+      "id": "1dRWJhy45E1Rq5wZAmPHt",
+      "description": "Update README as required",
+      "columnId": "column-todo"
+    },
     "55DAZwduwTvlaxaJC8hlX": {
       "id": "55DAZwduwTvlaxaJC8hlX",
       "description": "(Optional) Set up [Deepsource](https://app.deepsource.com/login) for static code analysis",
@@ -47,6 +87,14 @@
       "id": "column-todo",
       "title": "To do",
       "tasksIds": [
+        "G-1H47JpSI69kav1qZ-kp",
+        "RX4J5v4y5IOe_ucf8pMRT",
+        "EdPbrbJLllUHfZmCS80f7",
+        "MLLUsAhCKaKxvEXFY0HSq",
+        "gMYfaAh2RABMP8uZRQgNx",
+        "dC7QDBLH8BmHUfaYmIt81",
+        "P_NrSJQ8m91Odgz8E1fS6",
+        "1dRWJhy45E1Rq5wZAmPHt",
         "55DAZwduwTvlaxaJC8hlX",
         "FDFqCQvLm2mUlnTJ3Gna5",
         "O1qAByMoxhHOR-a_guL91",
@@ -69,4 +117,4 @@
       ]
     }
   ]
-}
+}

README.md

@@ -1,82 +1,133 @@
-## 🧩 Plugin Template for `mdast2docx` & `@m2d/remark-docx` <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
+# `@m2d/html` <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" height="40"/>
 
-[![test](https://github.com/md2docx/md2docx-plugin-template/actions/workflows/test.yml/badge.svg)](https://github.com/md2docx/md2docx-plugin-template/actions/workflows/test.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/md2docx/md2docx-plugin-template/maintainability) [![codecov](https://codecov.io/gh/md2docx/md2docx-plugin-template/graph/badge.svg)](https://codecov.io/gh/md2docx/md2docx-plugin-template) [![Version](https://img.shields.io/npm/v/@m2d/emoji.svg?colorB=green)](https://www.npmjs.com/package/@m2d/emoji) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/@m2d/emoji.svg)](https://www.npmjs.com/package/@m2d/emoji) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@m2d/emoji)
+[![Version](https://img.shields.io/npm/v/@m2d/html?color=green)](https://www.npmjs.com/package/@m2d/html) ![Downloads](https://img.shields.io/npm/d18m/@m2d/html) ![Bundle Size](https://img.shields.io/bundlephobia/minzip/@m2d/html)
 
-> This repository serves as a starting point for building plugins that extend the functionality of [`mdast2docx`](https://www.npmjs.com/package/mdast2docx), [`@m2d/core`](https://www.npmjs.com/package/@m2d/core) and [`@m2d/remark-docx`](https://www.npmjs.com/package/@m2d/remark-docx).
+> Parses embedded **HTML** into extended **MDAST nodes** to unlock full HTML-to-DOCX conversion support.
 
-<details>
-<summary style="cursor:pointer"><h2 style="display:inline-block">Features</h2></summary>
+---
+
+## 📦 Installation
+
+```bash
+npm install @m2d/html
+```
+
+```bash
+pnpm add @m2d/html
+```
 
-This template offers the following pre-configured features. Additionally, your repository will automatically be re-branded with the help of workflows and post-install scripts.
+```bash
+yarn add @m2d/html
+```
 
-✅ Monorepo powered by Turborepo and GitHub actions for automating building, testing, and deploying your plugin library
+---
 
-✅ Examples with Next.js, and Vite to showcase how your library can be utilized, also helps in quick manual testing
+## 🚀 Overview
 
-✅ Examples pre-configured for Light/Dark theme based on user preference
+The `@m2d/html` plugin for [`mdast2docx`](https://github.com/mayankchaudhari/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.
 
-✅ Examples ready to be deployed to Vercel
+---
 
-✅ Code of Conduct and contributing files, ready for customization
+## ⚠️ Important
 
-✅ Prettier and linter configured according to modern best practices (Feel free to add your flavor)
+> **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.
 
-✅ Recommended VSCode extensions - Prettier and [Kanban board](https://github.com/mayank1513/vscode-extension-trello-kanban-board) for code formatting and project management directly within your IDE
+---
 
-✅ Test setup with Vitest - A modern and fast testing framework supporting Jest-like APIs
+## 🛠️ Usage
 
-✅ Workflows to automate testing on every pull-request or code push event
+```ts
+import { htmlPlugin } from "@m2d/html";
 
-✅ Workflow to automatically publish and create GitHub releases when you update your library's `package.json` file.
+const plugins = [
+  htmlPlugin(), // ✅ Must come first
+  imagePlugin(),
+  tablePlugin(),
+];
+```
 
-✅ Workflow to automatically rebrand the entire template based on your repository name. (Refer [TODO.md](./TODO.md))
+---
 
-✅ Plus, this repo includes a quick checklist for configuring Codecov and other badges, setting up your docs website on GitHub pages, and more. See [Checklist](./TODO.md) or open TKB(Workspace) if you have installed the Trello-Kanban-Board extension.
+## 🧩 How It Works
 
-</details>
+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.
 
-> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Star [this repository](https://github.com/md2docx/md2docx-plugin-template) and share it with your friends.
+> This plugin enriches the AST to enable other plugins and core engine to convert it to docx.
 
 ---
 
-## Getting Started:
+## ✅ 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 |
 
-This template is based on [Turborepo Template](https://github.com/react18-tools/turborepo-template/). But this one is optimized for md2docx plugins. It includes pre-configured unit-tests, a lot of extra stuff provided by the turborepo-template is removed, and comes with dependencies and scripts optimized for md2docx plugin development.
+---
+
+## 🎨 Style Support
 
-To get started, simply click on the `"Use this template"` button to create a new repository based on this template, and install dependencies. Customize it according to your requirements for your next md2docx plugin.
+- `text-align`, `color`, `background-color`
+- `font-weight`, `font-style`, `text-decoration`
+- `text-transform`
+- `border`, `border-left`, etc.
+- `display: inline-block` and similar behaviors
 
-For detailed instructions and a checklist, please refer to [TODO.md](./TODO.md).
+---
 
-### 🤩 Don't forget to star [this repository](https://github.com/react18-tools/turborepo-template)!
+## ⚠️ Limitations
 
-Looking for a hands-on course to get started with Turborepo? Check out [React and Next.js with TypeScript](https://mayank-chaudhari.vercel.app/courses/react-and-next-js-with-typescript) and [The Game of Chess with Next.js, React, and TypeScript](https://www.udemy.com/course/game-of-chess-with-nextjs-react-and-typescript/?referralCode=851A28F10B254A8523FE)
+- 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.
 
 ---
 
-### 🧰 Helpful References
+## 🧪 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.
 
-- [`@m2d/core`](https://www.npmjs.com/package/@m2d/core) – Core MDAST to DOCX engine
-- [`@m2d/remark-docx`](https://www.npmjs.com/package/@m2d/remark-docx) – Remark plugin
-- [Unified Ecosystem](https://unifiedjs.com) – AST-based processors for markdown, html, etc.
-- [MDAST Spec](https://github.com/syntax-tree/mdast) – Markdown Abstract Syntax Tree
+> 🧵 **Contributions, ideas, and feedback are welcome!** Open an issue or PR anytime.
 
 ---
 
-### 💡 Derive Ideas from existing Plugins
+## 🔌 Related Plugins/Packages
 
-- `@m2d/math`: Parse math blocks and convert to equation DOCX
-- `@m2d/image`: Convert Markdown/HTML images to inline DOCX images
-- `@m2d/html`: Parse raw HTML into extended MDAST with styles
-- `@m2d/table`: Advanced table support with merged cells, widths, styles
+| Plugin                                               | Purpose                                |
+| ---------------------------------------------------- | -------------------------------------- |
+| [`@m2d/core`](https://npmjs.com/package/@m2d/core)   | Converts extended MDAST to DOCX        |
+| [`@m2d/image`](https://npmjs.com/package/@m2d/image) | Renders image nodes to DOCX            |
+| [`@m2d/table`](https://npmjs.com/package/@m2d/table) | Renders table nodes to DOCX            |
+| [`@m2d/list`](https://npmjs.com/package/@m2d/list)   | Enhanced list support (tasks, bullets) |
 
 ---
 
-### 🙌 Contribute
+## ⭐ Support Us
 
-If you’re building a plugin you'd like to share, let us know or open a PR in the [mdast2docx plugins repo](https://github.com/m2djs/mdast2docx)!
+If you find this useful:
+
+- ⭐ Star [mdast2docx](https://github.com/tiny-md/mdast2docx) on GitHub
+- ❤️ Consider [sponsoring](https://github.com/sponsors/mayank1513)
+
+---
 
-> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Enrolling in [our courses](https://mayank-chaudhari.vercel.app/courses) or [sponsor](https://github.com/sponsors/mayank1513) our work.
+## 🧾 License
 
-<hr />
+MIT © [Mayank Chaudhari](https://github.com/mayankchaudhari)
 
-<p align="center" style="text-align:center">with 💖 by <a href="https://mayank-chaudhari.vercel.app" target="_blank">Mayank Kumar Chaudhari</a></p>
+<p align="center">Made with 💖 by <a href="https://mayank-chaudhari.vercel.app" target="_blank">Mayank Kumar Chaudhari</a></p>

SECURITY.md

@@ -20,4 +20,4 @@ Note: We only accept pull requests addressing security vulnerabilities. Addition
 
 ## Reporting Vulnerabilities
 
-Kindly report vulnerabilities [here](https://github.com/md2docx/md2docx-plugin-template/security/advisories/new).
+Kindly report vulnerabilities [here](https://github.com/md2docx/html/security/advisories/new).

TODO.md

@@ -12,13 +12,13 @@
 - [ ] Install dependencies using `pnpm`
   - Run `pnpm i` to install dependencies
 - [ ] Make sure you run `pnpm rebrand` from the root directory to rebrand your repo.
-- [ ] 🌟 Enable [private vulnerability reporting]
+- [ ] 🌟 Enable [private vulnerability reporting](https://github.com/md2docx/html/security)
 - [ ] Set up `CodeCov`
   - Visit Codecov and set up your repo
-  - Create [repository secret] for `CODECOV_TOKEN`
+  - Create [repository secret]((https://github.com/md2docx/html/settings/secrets/actions)) for `CODECOV_TOKEN`
 - [ ] Set up `CodeClimate`
   - Visit CodeClimate and set up your repo
-  - Create [repository secret] for `CC_TEST_REPORTER_ID`
+  - Create [repository secret]((https://github.com/md2docx/html/settings/secrets/actions)) for `CC_TEST_REPORTER_ID`
   - Add `*.test.*` to ignore patterns on the website
   - Update Code Climate badge
 - [ ] Add `NPM_AUTH_TOKEN` to repository secrets to automate package publishing

examples/nextjs/package.json

@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@m2d/core": "latest",
-    "@m2d/emoji": "workspace:*",
+    "@m2d/emoji": "latest",
     "@repo/shared": "workspace:*",
     "mdast2docx": "0.3.0",
     "next": "^15.2.3",
@@ -27,7 +27,8 @@
     "remark-math": "^6.0.0",
     "remark-parse": "^11.0.0",
     "unified": "^11.0.5",
-    "webgl-generative-particles": "^0.0.1"
+    "webgl-generative-particles": "^0.0.1",
+    "@m2d/html": "workspace:*"
   },
   "devDependencies": {
     "@next/eslint-plugin-next": "^15.2.3",
@@ -38,4 +39,4 @@
     "@types/react-dom": "^19.0.4",
     "typescript": "^5.8.2"
   }
-}
+}

examples/vite/package.json

@@ -20,7 +20,8 @@
     "react18-loaders": "latest",
     "react18-themes": "^3.2.0",
     "@m2d/core": "latest",
-    "@m2d/emoji": "workspace:*"
+    "@m2d/emoji": "latest",
+    "@m2d/html": "workspace:*"
   },
   "devDependencies": {
     "@repo/eslint-config": "workspace:*",
@@ -31,4 +32,4 @@
     "typescript": "^5.8.2",
     "vite": "^6.2.2"
   }
-}
+}