feat(plugins): added plugin system

Author: Alexander Nortung

README.md

@@ -15,14 +15,14 @@ Write HTML → get Word, PDFs, spreadsheets, and more — all with one unified T
 
 ## How It Works
 
-Below is a high-level overview of the conversion pipeline. The library processes the HTML input through optional middleware steps, parses it into a structured intermediate representation, and then delegates to an adapter to generate the desired output format.
+Below is a high-level overview of the conversion pipeline. The library processes the HTML input through optional plugin steps, parses it into a structured intermediate representation, and then delegates to an adapter to generate the desired output format.
 
 ![Conversion Pipeline Diagram](./static/img/conversion-pipeline.png)
 
 The stages are:
 
 - **Input**: Raw HTML input as a string.
-- **Middleware**: One or more middleware functions can inspect or transform the HTML string before parsing (e.g., sanitization, custom tags).
+- **Plugins**: `beforeParse` hooks can inspect or transform the HTML string before parsing, and `afterParse` hooks can transform parsed `DocumentElement[]`. Deprecated middleware still works through internal plugin adaptation.
 - **Parser**: Converts the (possibly modified) HTML string into an array of `DocumentElement` objects, representing a structured AST.
 - **Adapter**: Takes the parsed `DocumentElement[]` and renders it into the target format (e.g., DOCX, PDF, Markdown) via a registered adapter.
 
@@ -38,7 +38,7 @@ The stages are:
 | **Style mapping engine**    | Define your own css mappings for the adapters and set per‑format defaults                                        |
 | **Custom tag handlers**     | Override or extend how any HTML tag is parsed                                                                    |
 | **Page sections & headers** | Use `<section class="page">`, `<section class="page-break">`, `<header>` and `<footer>` to control pages in DOCX |
-| **Middleware pipeline**     | Transform or sanitise HTML before parsing                                                                        |
+| **Plugin pipeline**         | Transform HTML before parsing or transform `DocumentElement[]` after parsing                                     |
 
 ---
 
@@ -183,6 +183,46 @@ const elements = await converter.parse('<p>Some HTML</p>');
 console.log(elements); // => DocumentElement[]
 ```
 
+### Plugins
+
+Plugins are the primary way to extend parsing.
+
+```ts
+const converter = init({
+  plugins: [
+    {
+      name: 'strip-scripts',
+      beforeParse: async (html) =>
+        html.replace(/<script[\s\S]*?>[\s\S]*?<\/script>/g, ''),
+    },
+    {
+      name: 'mark-generated',
+      afterParse: async (elements) =>
+        elements.map((element) => ({
+          ...element,
+          metadata: { ...element.metadata, generated: true },
+        })),
+    },
+  ],
+});
+```
+
+The built-in `minify` plugin is enabled by default. Disable built-in plugins with `enableDefaultPlugins: false`.
+
+Deprecated `middleware` and `clearMiddleware` still work:
+
+- `middleware` entries are adapted into `beforeParse` plugins internally
+- `clearMiddleware: true` implies `enableDefaultPlugins: false`
+- explicit `enableDefaultPlugins` overrides that implication
+
+You can also register plugins after construction:
+
+```ts
+converter.usePlugin({
+  beforeParse: async (html) => html.replace('Draft', 'Final'),
+});
+```
+
 ---
 
 ## 📚 Documentation & Demo

docs/docs/api/html-to-document.md

@@ -49,10 +49,12 @@ converter
 Initialize a new [`Converter`](./types) instance.
 
 - **options**: [`InitOptions`](./types) (optional)
-  - `middleware?: [`Middleware`](./types)[]` – custom middleware functions.
+  - `plugins?: [`Plugin`](./types)[]` – plugin hooks for pre-parse and post-parse transforms.
+  - `enableDefaultPlugins?: boolean` – enable or disable built-in plugins.
+  - `middleware?: [`Middleware`](./types)[]` – deprecated middleware compatibility layer.
   - `tags?: { tagHandlers?: [`TagHandlerObject`](./types)[]; defaultStyles?: ...; defaultAttributes?: ... }` – custom tag handlers and default tag options.
 - `adapters?: { defaultStyles?: ...; register?: { format: string; adapter: [`AdapterProvider`](./types); config?: object; createAdapter?: ... }[] }` – register adapters, customize construction per adapter, and pass adapter-specific config.
-  - `clearMiddleware?: boolean` – clear default middleware.
+  - `clearMiddleware?: boolean` – deprecated legacy switch that disables default plugins by implication.
   - `domParser?: [`IDOMParser`](./types)` – custom DOM parser implementation.
 
 Returns: a configured [`Converter`](./types) instance.
@@ -62,6 +64,7 @@ Returns: a configured [`Converter`](./types) instance.
 Explore further customization using the links below:
 
 - [Initialization](./init)
+- [Plugins](./plugins)
 - [Custom Tag Handlers](./tags)
 - [Middleware](./middleware)
 - [Style Mappings & Default Styles](./style-mappings)
@@ -78,6 +81,10 @@ Class for parsing and converting HTML to document formats.
 Create a Converter with raw options:
 
 - `tags?: ...` – alias for `options.tags` in `init`.
+- `plugins?: [`Plugin`](./types)[]`
+- `enableDefaultPlugins?: boolean`
+- `middleware?: [`Middleware`](./types)[]` (deprecated)
+- `clearMiddleware?: boolean` (deprecated)
 - `adapters?: ...`
 - `registerAdapters?: { format: string; adapter: [`IDocumentConverter`](./types) }[]`
 - `domParser?: [`IDOMParser`](./types)`
@@ -107,6 +114,12 @@ Register a middleware function to process HTML before parsing.
 
 - `mw`: [`Middleware`](./types) function.
 
+##### usePlugin(plugin: [`Plugin`](./types)): void
+
+Register a plugin after construction.
+
+- `plugin`: [`Plugin`](./types) object.
+
 ##### registerConverter(name: string, converter: [`IDocumentConverter`](./types)): void
 
 Register a custom document converter adapter.
@@ -121,6 +134,7 @@ Register a custom document converter adapter.
 | [`InitOptions`](./types)        | Options for initializing the converter via `init`.                                                                                          |
 | [`ConverterOptions`](./types)   | Internal options for the `Converter` constructor.                                                                                           |
 | [`Converter`](./types)          | Main class for conversion and parsing.                                                                                                      |
+| [`Plugin`](./types)             | Optional `beforeParse` and `afterParse` hooks for extending the conversion pipeline.                                                        |
 | [`Middleware`](./types)         | Asynchronous function taking an HTML string and returning a Promise of string.                                                              |
 | [`TagHandler`](./types)         | Handler that processes an `HTMLElement` with optional `TagHandlerOptions` and returns a `DocumentElement` or an array of `DocumentElement`. |
 | [`TagHandlerObject`](./types)   | `{ key: string; handler: TagHandler }`                                                                                                      |

docs/docs/api/init.md

@@ -7,7 +7,7 @@ sidebar_position: 2
 
 # Initialization
 
-The `init` function is your main entry point to configure and initialize the converter engine. It returns a `Converter` instance that can parse HTML and convert it into document formats like DOCX, PDF, or Markdown. Through `init`, you can register custom adapters, tag handlers, middleware, and default styles to control how HTML is interpreted and styled.
+The `init` function is your main entry point to configure and initialize the converter engine. It returns a `Converter` instance that can parse HTML and convert it into document formats like DOCX, PDF, or Markdown. Through `init`, you can register custom adapters, tag handlers, plugins, and default styles to control how HTML is interpreted and styled.
 
 ## Quick Start
 
@@ -42,13 +42,62 @@ declare function init(options?: InitOptions): Converter;
 
 The `options` object conforms to the [`InitOptions`](./types) type and supports the following properties:
 
+### `plugins?: Plugin[]`
+
+Register one or more plugins for the converter pipeline.
+
+- **Type:** [`Plugin`](./types)[]
+- **Default:** the built-in `minify` plugin is enabled unless disabled by `enableDefaultPlugins: false`, or implicitly by legacy `clearMiddleware: true`
+- **Hooks:**
+  - `beforeParse?(html)` transforms the raw HTML string
+  - `afterParse?(elements)` transforms the parsed `DocumentElement[]`
+- **Order:** plugins run in array order; all `beforeParse` hooks run before parsing and all `afterParse` hooks run after parsing
+- **Errors:** plugin failures fail fast and surface their original errors
+- **Example:**
+
+  ```ts
+  import { init } from 'html-to-document';
+
+  const converter = init({
+    plugins: [
+      {
+        name: 'strip-scripts',
+        beforeParse: async (html) =>
+          html.replace(/<script[\s\S]*?>[\s\S]*?<\/script>/g, ''),
+      },
+      {
+        name: 'mark-paragraphs',
+        afterParse: async (elements) =>
+          elements.map((element) =>
+            element.type === 'paragraph'
+              ? {
+                  ...element,
+                  metadata: { ...element.metadata, sanitized: true },
+                }
+              : element
+          ),
+      },
+    ],
+  });
+  ```
+
+### `enableDefaultPlugins?: boolean`
+
+Controls whether built-in plugins are registered.
+
+- **Type:** boolean
+- **Default:** `true`, unless `clearMiddleware: true` is set and `enableDefaultPlugins` is not explicitly provided
+- **Current built-in plugin:** `minify`
+
+See [Plugins](./plugins) for details.
+
 ### `middleware?: Middleware[]`
 
-Register one or more middleware functions to transform the HTML before parsing.
-Middleware lets you transform or sanitize HTML before parsing—e.g., stripping scripts, normalizing whitespace, or injecting metadata.
+Deprecated compatibility layer for HTML preprocessing.
 
 - **Type:** [`Middleware`](./types)[]
-- **Default:** _[minifyMiddleware] applied automatically unless `clearMiddleware` is `true`_
+- **Status:** deprecated; prefer `plugins` with `beforeParse`
+- **Behavior:** each middleware entry is internally adapted into a plugin
 - **Example:**
 
   ```ts
@@ -62,11 +111,12 @@ Middleware lets you transform or sanitize HTML before parsing—e.g., stripping
 
 ### `clearMiddleware?: boolean`
 
-Skips registering the default `minifyMiddleware`. When `true`, only your provided middleware functions will be used.
+Deprecated compatibility switch for the old middleware model.
 
 - **Type:** boolean
 - **Default:** `false`
-- **Default:** `false`
+- **Status:** deprecated; prefer `enableDefaultPlugins: false`
+- **Behavior:** implies `enableDefaultPlugins: false` by default, but explicit `enableDefaultPlugins` overrides that legacy implication
 
 ### `styleInheritance?`
 
@@ -269,12 +319,15 @@ Use a custom DOM parser implementation.
 ```ts
 import { init } from 'html-to-document';
 import { MyAdapter } from './my-adapter';
-import { customMiddleware } from './middleware';
 import { CustomParser } from './parser';
 
 const converter = init({
-  clearMiddleware: false,
-  middleware: [customMiddleware],
+  plugins: [
+    {
+      beforeParse: async (html) =>
+        html.replace(/<script[\s\S]*?>[\s\S]*?<\/script>/g, ''),
+    },
+  ],
   tags: {
     defaultStyles: [{ key: 'p', styles: { marginBottom: 8 } }],
   },
@@ -293,6 +346,7 @@ converter
 
 ## Learn More
 
+- [Plugins and hooks](./plugins)
 - [Building a custom adapter](./converters)
 - [Available tag handlers and structure](./tags)
 - [DocumentElement schema reference](./types)

docs/docs/api/middleware.md

@@ -2,12 +2,16 @@
 id: middleware
 title: Middleware
 sidebar_label: Middleware
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Middleware
 
-Middleware functions run on the HTML string _before_ it is parsed into `DocumentElement` nodes. They allow you to transform, sanitize, or minify the HTML content.
+`middleware` is deprecated and kept as a compatibility layer for the newer plugin system.
+
+Middleware functions still run on the HTML string _before_ it is parsed into `DocumentElement` nodes, but internally each middleware entry is adapted into a plugin with a `beforeParse` hook.
+
+Use [Plugins](./plugins) for new code.
 
 ## Signature
 
@@ -19,17 +23,20 @@ type Middleware = (html: string) => Promise<string>;
 
 See the [Types Reference](./types) for the full definition.
 
-## Default Middleware
+## Default Middleware Behavior
+
+The old built-in whitespace minifier now exists as the default `minify` plugin. `clearMiddleware: true` still disables it by default because it implies `enableDefaultPlugins: false` unless you explicitly override that.
+
+The default behavior is still:
 
-By default, `init()` applies a built-in whitespace-minifying middleware (unless you set `clearMiddleware: true`). This default middleware:
 - Strips HTML comments (`<!-- ... -->`)
 - Collapses consecutive whitespace into a single space (outside `<pre>`)
 - Removes unnecessary whitespace between tags
 - Trims leading and trailing whitespace
 
 ## Custom Middleware
 
-There are two ways to register your own middleware:
+There are two legacy ways to register middleware:
 
 ### 1. Via `init` options
 
@@ -41,7 +48,7 @@ const stripScripts: Middleware = async (html) =>
   html.replace(/<script[\s\S]*?>[\s\S]*?<\/script>/g, '');
 
 const converter = init({
-  clearMiddleware: true,    // skip default minifier
+  clearMiddleware: true, // skip default minifier
   middleware: [stripScripts],
 });
 ```
@@ -56,6 +63,7 @@ converter.useMiddleware(stripScripts);
 
 > **Note:** Middleware functions are executed in the order they are passed in or registered. Make sure to arrange them accordingly if one depends on the output of another.
 
+When both `plugins` and deprecated `middleware` are provided through `init()` or the `Converter` constructor, plugin `beforeParse` hooks run first and adapted middleware runs after them.
 
 ## Example: Sanitizing HTML
 
@@ -73,4 +81,16 @@ const converter = init({
 converter.convert('<p style="color:red">Hello</p>', 'docx')
   .then(buffer => /* ... */)
   .catch(console.error);
-```
+```
+
+## Migration to Plugins
+
+```ts
+const converter = init({
+  plugins: [
+    {
+      beforeParse: async (html) => html.replace(/ style="[^"]*"/g, ''),
+    },
+  ],
+});
+```