Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
bbacbdc
fix(html): read braced attribute values, --> comments and the first d…
onmax Nov 1, 2026
0dea7f4
fix(html): pair implied end tags and keep inline content like browsers
onmax Nov 1, 2026
372e58a
fix(html): do not wrap a standalone comment in a paragraph
onmax Nov 1, 2026
dc13fe0
fix(html): decode character references and parse tags inside <pre>
onmax Nov 1, 2026
a804a4b
fix(parse): keep an author-written <p> when autoUnwrap runs
onmax Nov 1, 2026
6cf0e6b
docs(html): document the tag grammar, implied end tags and <pre> cont…
onmax Nov 1, 2026
12aead5
fix(html): find closing tags in linear time and within their container
onmax Nov 1, 2026
eba89e6
fix(html): keep the text of literal HTML through parse and render
onmax Nov 1, 2026
b5ed21c
fix(html): index closing tags once, match raw tags exactly, keep lite…
onmax Nov 1, 2026
564af21
fix(html): write HTML text as character references so it reads the sa…
onmax Nov 1, 2026
ff68f64
refactor(html): consolidate regression coverage and trim parsing code
onmax Nov 1, 2026
7c3974b
test(html): drop tests the fixture table already covers
onmax Nov 1, 2026
9babfd7
refactor(html): drop stray `</br>` check now handled before the stack…
onmax Nov 2, 2026
d7edad8
test(html): move HTML parsing cases into SPEC fixtures
onmax Nov 2, 2026
7ca796e
perf(html): keep the render html handler's per-element context edit s…
onmax Nov 4, 2026
3487c65
test(html): expect unclosed prose tags to stay inline in components
onmax Nov 5, 2026
1e911e3
test(core): refresh bundle snapshot after HTML parsing fixes
onmax Nov 5, 2026
514f7db
Merge remote-tracking branch 'origin/main' into fix/html-parsing-525
onmax Nov 16, 2026
14c4491
fix(html): restore mixed-case tags, braced paths and streamed closers…
onmax Nov 16, 2026
58bc050
fix(html): keep raw bodies, semicolonless references and spacing thro…
onmax Nov 16, 2026
45e7eab
fix(html): keep a trailing newline and carriage returns in HTML text …
onmax Nov 16, 2026
9b7c9d9
refactor(html): shorten comments on the parse and save fixes
onmax Nov 16, 2026
7f8457b
test(core): refresh bundle snapshot after the merge with main
onmax Nov 16, 2026
78488e2
fix(security): check URLs in the strings of a `{…}` style
onmax Nov 16, 2026
c7dc995
perf(html): match attributes with exec and skip lookups for common tags
onmax Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 30 additions & 3 deletions packages/comark/SPEC/HTML/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# HTML parsing contract

Behavioral contract for embedded HTML. Fixtures in this directory are the user-facing cases. `test/html-block.test.ts` covers the option matrix and the cases deferred below.
Behavioral contract for embedded HTML. Fixtures in this directory are the user-facing cases. `test/html-tags.test.ts` covers `markdown: false`, streaming, and large inputs; `test/html-block.test.ts` covers the option matrix and the cases deferred below.

HTML tags become element nodes with `$: { html: 1, block: 0 | 1 }`. A node without `$` is markdown-originated (`<strong>` from `**bold**` is `['strong', {}, 'bold']`).

Expand All @@ -15,6 +15,8 @@ HTML tags become element nodes with `$: { html: 1, block: 0 | 1 }`. A node witho

Void tags (`img`, `br`, …) are always `block: 0`.

A non-void open tag that follows text in its paragraph (`GET /apps/<id>`, `- **a** <b>c`) is prose, not a container. It ends with its paragraph, `block: 0`, unless a later paragraph of the same container holds its close tag. A close tag in a nested container (`::card`, a blockquote) or past the end of the container does not count. A tag that starts its paragraph keeps collecting the blocks after it.

Consecutive same-paragraph tags stay inline even if indented on following lines:

```md
Expand All @@ -41,7 +43,13 @@ Blank-line bodies parse as markdown in both modes. CommonMark ends the HTML bloc

`<style>`, `<pre>`, `<script>`, and `<textarea>` always stay raw blocks, including with attributes. None of those bodies is markdown, in either mode. The match is the tag name plus a boundary, so `<prelude>` is not `<pre>` and `<scripture>` is not `<script>`.

All four keep every character between the tags, including the leading newline and indentation. Inner tags stay text until the matching closer, including inside `<pre>` and `<style>`.
All four keep every character between the tags, including the leading newline and indentation, whether the element starts its block or follows text in a paragraph (`before <pre>**x**</pre>`) as long as its closer is in that paragraph. What else the body means follows the HTML spec:

| Tag | Inner tags | Character references |
| --- | --- | --- |
| `<style>`, `<script>` | text until the matching closer | kept as written |
| `<textarea>` | text until the matching closer | decoded |
| `<pre>` | HTML (`<pre><code>…</code></pre>`), unless an open tag has no closer inside the `<pre>` (`Array<string>`), which stays text | decoded |

```html
<pre>
Expand All @@ -52,6 +60,8 @@ All four keep every character between the tags, including the leading newline an

is the text `\n const x = 1\n **not**\n`, not a trimmed line and not a `strong`.

Character references are decoded in text, with or without markdown: `&amp;`, `&lt;`, `&#65;`. As in markdown, a reference needs its `;` (`&copy` stays), and an unknown name stays. Written back, the text keeps its meaning: in HTML and Markdown output a decoded `&lt;` or `<b>` in an element's text is encoded again (`&amp;lt;`), so a reader sees the characters the author wrote. `<script>` and `<style>` text is written as it was read.

### Whitespace in a literal body

`markdown: false` keeps horizontal spaces. A space between tags (`</a> <a>`) and a space beside text (`Hello <em>`) are content.
Expand All @@ -66,11 +76,28 @@ Runs that contain a newline are structural. Leading indent after a newline is st

with `markdown: false` is the text `Hello ` plus `<em>`, not `"\n Hello "` plus `<em>`.

## Tags

One grammar reads a tag in the inline rule and in the raw-block splitter (`src/internal/parse/html-tag.ts`). It is CommonMark's, plus:

- An attribute value may be a balanced `{…}` expression, up to four levels deep: `<div style={{a: 1}}>` has `style="{{a: 1}}"`. The text is kept as written. Only braces are counted, not JavaScript: a brace inside a string (`{{a: "}"}}`) is not skipped, so the tag is not recognized.
- A comment may end in `--->`, as in HTML: `<!--- a --->` is a comment with the text `- a -`.

When an attribute repeats, the first value wins, as in HTML.

A comment in a block of its own is a comment node, not a paragraph holding one, whatever its indentation.

A few end tags are implied, as in HTML: a stray `</br>` is a `<br>`, and a `<p>` closes an open `<p>` (not across a `table`, `td`, `th`, `caption`, `button`, `template`, `object`, `marquee`, or `applet`). Nothing else is closed implicitly; for example a `<div>` does not close a `<p>`.

## Inline content in a block

Inside an element that collects blocks, a paragraph's inline content stays in one `p`. Markdown inline nodes (images, line breaks, components, math) always belong to it. An HTML tag does when it is one of `strong`, `em`, `del`, `code`, `a`, `span`, `sub`, `sup`, `kbd`, `img`, `br`, or a custom element (a name with a `-`) that closed in its paragraph. An author-written element that is alone in its paragraph is not wrapped, except for the first group.

## How a block becomes a tree

1. markdown-exit tokenizes with `html: true`.
2. When `markdown` is true, the built-in `html_block` rule is narrowed to `<style>`, `<pre>`, `<script>`, and `<textarea>`. Every other closed HTML region falls through to the normal block/inline rules, so `**`, `` ` ``, and nested tags tokenize as markdown. This override is the feature. It reads markdown-exit's private block ruler (`__rules__`); a markdown-exit upgrade that renames or stops consulting `html_block` silently disables markdown-in-HTML.
3. Regions that remain `html_block` (those four tags, and every closed HTML block when `markdown` is false) are split into `html_inline` + literal `text` and wrapped in a paragraph so the same walk pairs them. The four raw-tag bodies are not split.
3. Regions that remain `html_block` (those four tags, and every closed HTML block when `markdown` is false) are split into `html_inline` + literal `text` and wrapped in a paragraph so the same walk pairs them. `<pre>` bodies are split into HTML tags and text; the other three bodies stay text.
4. The tree walk keeps an HTML stack across blocks, the way hast-util-raw feeds parse5. An open tag pushes a frame. Later paragraphs and blocks fill it. A matching close pops it and auto-closes mismatched frames in between. `</div><div>` emits the closed `div` as a sibling of the new open frame, not as its child.

Two scanners must agree on what a tag is: the splitter for raw `html_block` text (`htmlToTokens` in `src/plugins/html.ts`) and the inline opener/closer parser (`parseHtmlInline` in `src/internal/parse/utils.ts`). A tag one accepts and the other rejects becomes a text leaf or an unclosed frame.
Expand Down
48 changes: 48 additions & 0 deletions packages/comark/SPEC/HTML/attribute-braced-inline.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
## Input

```md
a <b data={`x ${1}`} on={{ k: { v: 1 } }} d>y</b>
```

## AST

```json
{
"frontmatter": {},
"meta": {},
"nodes": [
[
"p",
{},
"a ",
[
"b",
{
"$": {
"html": 1,
"block": 0
},
"data": "{`x ${1}`}",
"on": "{{ k: { v: 1 } }}",
"d": true
},
"y"
]
]
]
}
```

## HTML

```html
<p>
a <b data="{`x ${1}`}" on="{{ k: { v: 1 } }}" d>y</b>
</p>
```

## Markdown

```md
a <b data="{`x ${1}`}" on="{{ k: { v: 1 } }}" d>y</b>
```
40 changes: 40 additions & 0 deletions packages/comark/SPEC/HTML/attribute-duplicate-case.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
## Input

```md
<a href=x HREF=y title>t</a>
```

## AST

```json
{
"frontmatter": {},
"meta": {},
"nodes": [
[
"a",
{
"$": {
"html": 1,
"block": 0
},
"href": "x",
"title": true
},
"t"
]
]
}
```

## HTML

```html
<a href="x" title>t</a>
```

## Markdown

```md
<a href="x" title>t</a>
```
38 changes: 38 additions & 0 deletions packages/comark/SPEC/HTML/attribute-duplicate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
## Input

```md
<img alt="first" alt="second">
```

## AST

```json
{
"frontmatter": {},
"meta": {},
"nodes": [
[
"img",
{
"$": {
"html": 1,
"block": 1
},
"alt": "first"
}
]
]
}
```

## HTML

```html
<img alt="first">
```

## Markdown

```md
<img alt="first">
```
45 changes: 45 additions & 0 deletions packages/comark/SPEC/HTML/attribute-jsx-expression.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
## Input

```md
<div style={{a: 1}}>

x
```

## AST

```json
{
"frontmatter": {},
"meta": {},
"nodes": [
[
"div",
{
"$": {
"html": 1,
"block": 1
},
"style": "{{a: 1}}"
},
"x"
]
]
}
```

## HTML

```html
<div style="{{a: 1}}">
x
</div>
```

## Markdown

```md
<div style="{{a: 1}}">
x
</div>
```
43 changes: 43 additions & 0 deletions packages/comark/SPEC/HTML/attribute-prototype-name.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
## Input

```md
<div constructor="a" constructor="b">x</div>
```

## AST

```json
{
"frontmatter": {},
"meta": {},
"nodes": [
[
"div",
{
"$": {
"html": 1,
"block": 1
},
"constructor": "a"
},
"x"
]
]
}
```

## HTML

```html
<div constructor="a">
x
</div>
```

## Markdown

```md
<div constructor="a">
x
</div>
```
74 changes: 74 additions & 0 deletions packages/comark/SPEC/HTML/block+element-alone.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
options:
autoUnwrap: false
---

## Input

```md
<div>

<my-el>y</my-el>

<img src="a">

</div>
```

## AST

```json
{
"frontmatter": {},
"meta": {},
"nodes": [
[
"div",
{
"$": {
"html": 1,
"block": 1
}
},
[
"my-el",
{
"$": {
"html": 1,
"block": 0
}
},
"y"
],
[
"img",
{
"$": {
"html": 1,
"block": 0
},
"src": "a"
}
]
]
]
}
```

## HTML

```html
<div>
<my-el>y</my-el>
<img src="a">
</div>
```

## Markdown

```md
<div>
<my-el>y</my-el>
<img src="a">
</div>
```
Loading
Loading