@tiptap/markdown: HTML comment inside a heading crashes with RangeError: Invalid content for node type heading

[JustinTulloss]

Affected Packages

@tiptap/markdown

Tiptap Version

3.28.0

Browser Used

Chrome

What happened?

Parsing markdown that contains an inline HTML comment inside a heading crashes the editor:

RangeError: Invalid content for node type heading
    at setNodeMarkup
    at appendTransaction   (@tiptap/extension-table-of-contents)

Steps to reproduce

Load this markdown into an editor built from StarterKit + @tiptap/extension-table-of-contents, in a browser (real DOM present):

## Week of <!-- date -->

The document loads, then the table-of-contents plugin throws on the next transaction.

Root cause

1. parseHTMLToken in MarkdownManager routes unrecognized HTML through generateJSON (a real ProseMirror DOM parse). This path is only taken when window.DOMParser exists — headless, it already falls back to literal text, so the bug is browser-only.
2. generateJSON("<!-- date -->") has no element to keep, so it returns an empty paragraph: { type: "doc", content: [{ type: "paragraph" }] }.
3. For an inline comment token, that empty block paragraph gets spliced into the heading's inline content — an invalid document that nonetheless loads.
4. @tiptap/extension-table-of-contents calls setNodeMarkup on every heading on every transaction (to stamp data-toc-id), which re-validates the node → RangeError. A comment in a heading is the worst case because the TOC plugin touches every heading constantly.

The unrecognized-HTML guard added in #7916 keys off tag names via /<\/?([a-zA-Z][\w-]*)/, which never matches <!--. So a comment is treated as recognized HTML and still hits generateJSON, instead of being sent through the existing htmlAsLiteralText fallback.

Suggested fix

In MarkdownManager.parseHTMLToken, detect comment-only markup before the DOM parse and fall back to literal text:

     if (!html.trim()) {
       return null;
     }
+    // A comment-only token has no element for the DOM parser to keep, so
+    // generateJSON reduces it to an empty paragraph; returning that block node
+    // into inline content crashes on re-validation. Comments carry no tag name,
+    // so isUnrecognizedHtml misses them. Pass comment-only markup through as text.
+    if (/^\s*(?:<!--[\s\S]*?-->\s*)+$/.test(html)) {
+      return this.htmlAsLiteralText(html, !!token.block);
+    }
     if (this.isUnrecognizedHtml(html)) {
       return this.htmlAsLiteralText(html, !!token.block);
     }

Detecting the comment before the parse (rather than checking for an empty paragraph after) matters: <!-- x --> and a genuine empty <p></p> both reduce to an empty paragraph, so a post-parse check would wrongly convert real empty <p></p> blocks to literal text too. The up-front check is comment-specific.

Environment

• @tiptap/markdown@3.28.0
• Browser (bug does not reproduce headless / without window.DOMParser)
• With @tiptap/extension-table-of-contents (any extension that runs setNodeMarkup on headings triggers it; TOC is just the most common)

Expected Behavior

A comment-only token should be passed through via htmlAsLiteralText (matching the headless path and CommonMark's "raw HTML passes through verbatim" semantics), not turned into an empty block node in inline content.

Reproducible Example URL (Optional)

No response

Additional Context (Optional)

No response

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• [Markdown]: editor.markdown.parse() fails to parse HTML comments, returning empty paragraph #7720

🔗 Related PRs

#8008 - fix(markdown): recover blank lines absorbed into block token raw [open]
#8017 - fix(markdown): never parse to an empty document (fixes setContent crash) [open]
#8026 - fix(core): input rules no longer crash when the match spans an inline atom node [open]
#8103 - fix(extension-table): backfill empty cells on slice parse (#6237) [open]
#8111 - fix(markdown): keep non-breaking-space-only content instead of serializing to empty (#7495) [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Add a small, comment-specific regex check in parseHTMLToken that runs before the DOM parse and reuses the existing htmlAsLiteralText fallback.
• Placing it before generateJSON is the key detail — it avoids the empty-paragraph ambiguity that a post-parse check would create.
• Add a new spec in the browser (happy-dom) environment to reproduce the original crash scenario and confirm comments now pass through as text while real empty paragraphs are left untouched.

Implementation Steps

Fix the comment-handling bug

The goal here is simple: catch comment-only HTML before it reaches the DOM parser and send it through the existing literal-text fallback. This matches what already happens headless and keeps the raw comment text in the document (this follows CommonMark's rule that raw HTML should just pass through as-is).

Add a comment-only guard in parseHTMLToken

Route comment-only markup to the literal-text fallback so it never becomes an empty block node.

• Edit packages/markdown/src/MarkdownManager.ts, inside parseHTMLToken.
• After the empty-HTML check (if (!html.trim()) return null) and before the isUnrecognizedHtml check, add a check that detects HTML made up only of one or more comments (with optional surrounding whitespace), e.g. matching /^\s*(?:<!--[\s\S]*?-->\s*)+$/.
• When it matches, return this.htmlAsLiteralText(html, !!token.block) — reusing the existing helper so block vs. inline handling stays consistent.
• Add a short comment explaining why the check must happen before the DOM parse: a real empty <p></p> also reduces to an empty paragraph, so a post-parse check would wrongly rewrite genuine empty paragraphs too. The up-front check is comment-specific.

🤖 Prompt for AI agents

Goal: stop HTML comments from crashing the editor by catching them before they
hit the real DOM parser.

- Open `packages/markdown/src/MarkdownManager.ts` and find the `parseHTMLToken`
method.
- Right after the existing empty-HTML check (`if (!html.trim()) return null`),
and BEFORE the `isUnrecognizedHtml` check, add a new check.
- This new check should detect if the HTML is made up of only comment(s) -
possibly with whitespace around them. Use a regex like
`/^\s*(?:<!--[\s\S]*?-->\s*)+$/` to test this.
- If it matches, return `this.htmlAsLiteralText(html, !!token.block)`. This
reuses the existing helper, so block vs inline handling still works the same
way.
- Add a brief code comment explaining why this check must run BEFORE the DOM
parse: a genuine empty `<p></p>` also turns into an empty paragraph after
parsing, so checking after the parse would wrongly treat real empty paragraphs
as if they were comments. Doing the check up-front, before parsing, avoids that
mix-up because it's specifically looking for comment syntax.

Research

The @tiptap/markdown package turns Markdown into ProseMirror JSON. The main brain behind this is MarkdownManager (found in packages/markdown/src/MarkdownManager.ts). It has a private method called parseHTMLToken that decides how to handle raw HTML tokens found in the Markdown:

• If the HTML is empty, it returns null.
• If the HTML has a tag that isn't recognized (checked via isUnrecognizedHtml), it keeps it as plain literal text.
• If there's no browser DOM available, it also keeps it as literal text.
• Otherwise, it calls generateJSON to do a real DOM parse.

Here's the bug: an HTML comment (like <!-- ... -->) doesn't have a tag name, so the isUnrecognizedHtml regex (/<\/?([a-zA-Z][\w-]*)/) never matches it. This means in a browser, the comment sneaks past the check and goes straight to generateJSON. That function turns the comment into an empty paragraph node - which is a block-level node. When that block node ends up inside a heading's inline content, the document becomes invalid, and things crash on the very next transaction.

Tests for this package live in packages/markdown/__tests__/*.spec.ts. They use a file-level @vitest-environment happy-dom (real DOM, simulates browser) or node (no DOM, simulates headless) directive at the top to control which code path gets tested.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Goal: stop HTML comments from crashing the editor by catching them before they
hit the real DOM parser.

- Open `packages/markdown/src/MarkdownManager.ts` and find the `parseHTMLToken`
method.
- Right after the existing empty-HTML check (`if (!html.trim()) return null`),
and BEFORE the `isUnrecognizedHtml` check, add a new check.
- This new check should detect if the HTML is made up of only comment(s) -
possibly with whitespace around them. Use a regex like
`/^\s*(?:<!--[\s\S]*?-->\s*)+$/` to test this.
- If it matches, return `this.htmlAsLiteralText(html, !!token.block)`. This
reuses the existing helper, so block vs inline handling still works the same
way.
- Add a brief code comment explaining why this check must run BEFORE the DOM
parse: a genuine empty `<p></p>` also turns into an empty paragraph after
parsing, so checking after the parse would wrongly treat real empty paragraphs
as if they were comments. Doing the check up-front, before parsing, avoids that
mix-up because it's specifically looking for comment syntax.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!