- 
-
+# PostHTML Parser
+
+Parse HTML/XML into a [PostHTML AST](#posthtml-ast-format) using [htmlparser2](https://github.com/fb55/htmlparser2).
## Installation
Requires Node.js `^20.19.0 || >=22.12.0`. These versions support synchronous CommonJS loading of the ESM-only `htmlparser2` backend. Both `require()` and native ESM imports expose the synchronous `parser` API.
-TypeScript consumers need TypeScript 5.3 or later. For development, use Node.js 24 (`nvm install && nvm use`).
+TypeScript consumers need TypeScript 5.3 or later.
```sh
npm install posthtml-parser
@@ -22,156 +14,69 @@ npm install posthtml-parser
## Usage
-Input HTML:
-
-```html
-
- Cat
-
-```
-
-Parse with `posthtml-parser`:
-
```js
-import fs from 'fs'
-import { parser } from 'posthtml-parser'
+import { parser } from "posthtml-parser";
-const html = fs.readFileSync('path/to/input.html', 'utf-8')
-
-console.log(parser(html))
+const tree = parser('Hello');
+console.log(tree);
```
-Resulting PostHTML AST:
+Result:
```js
[
{
- tag: 'a',
+ tag: "a",
attrs: {
- class: 'animals',
- href: '#'
+ class: "link"
},
- content: [
- '\n ',
- {
- tag: 'span',
- attrs: {
- class: 'animals__cat',
- style: 'background: url(cat.png)'
- },
- content: ['Cat']
- },
- '\n'
- ]
+ content: ["Hello"]
}
]
```
-## PostHTML AST Format
-
-Any parser used with PostHTML should return a standard PostHTML [Abstract Syntax Tree](https://www.wikiwand.com/en/Abstract_syntax_tree) (AST).
-
-Fortunately, this is a very easy format to produce and understand. The AST is an array that can contain strings and objects. Strings represent plain text content, while objects represent HTML tags.
-
-Tag objects generally look like this:
+CommonJS is supported too:
```js
-{
- tag: 'div',
- attrs: {
- class: 'foo'
- },
- content: ['hello world!']
-}
+const { parser } = require("posthtml-parser");
```
-Tag objects can contain three keys:
-
-- The `tag` key takes the name of the tag as the value. This can include custom tags.
-- The optional `attrs` key takes an object with key/value pairs representing the attributes of the html tag. A boolean attribute has an empty string as its value.
-- The optional `content` key takes an array as its value, which is a PostHTML AST. In this manner, the AST is a tree that should be walked recursively.
-
-## Options
-
-### `directives`
-
-Type: `Array`\
-Default: `[{name: '!doctype', start: '<', end: '>'}]`
-
-Adds processing of custom directives.
-
-The property ```name``` in custom directives can be of `String` or `RegExp` type.
-
-### `xmlMode`
-
-Type: `Boolean`\
-Default: `false`
-
-Indicates whether special tags (`
-