Skip to content

fix(mdxish): keep html comments syntax as written when serializing - #1692

Merged
eaglethrost merged 4 commits into
nextfrom
dimas/rm-19746-investigate-comment-syntax-normalization-and
Nov 19, 2026
Merged

eaglethrost merged 4 commits into
nextfrom
dimas/rm-19746-investigate-comment-syntax-normalization-and

Conversation

@eaglethrost

@eaglethrost eaglethrost commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor
🎫 Resolve RM-19746

🎯 What does this PR do?

mdxishMdastToMd rewrote every <!-- --> to {/* */}. That came from the MDX compiler, where HTML comments don't parse. MDX-ish parses and hides both forms so we don't need to serialise them unconditionally to JSX, and also the rewrite lost content on save:

  • <!-- a */ b --> saves as {/* a */ b */}, which renders as visible text
  • <!-- one --><!-- two --> leaks / two /} as visible text on the second save
  • <style><!-- … --></style> drops the style rule
  • # Title <!-- note --> changes its heading id on save, breaking anchor links
  • In the editor, a reload with live collab flashes {/* */} and then shows <!-- -->, because the live doc keeps what was typed

The MDX-ish serializer now writes html nodes as they are. mdx() still converts comments.

🧪 QA tips

  • compatability.test.tsx: the mdxishMdastToMd rows from fix(compatibility): convert each html comment separately in compiled html blocks #1686 now expect comments kept as written; the mdx rows are unchanged
  • mdxishMdastToMd.test.ts: round trips for block, inline, */, adjacent, <style> and heading comments; all fail without the fix
  • An MDX-ish → MDX rollback can't compile <!-- -->. That's already true today: raw mode, the API and git sync store it as written

Demo in the readme app:

Screen.Recording.2026-11-18.at.4.41.24.pm.mov

@greptile-apps

greptile-apps Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable bugs were found.

Reviews (1) · Last reviewed commit: "fix(mdxish): keep html comments as writt..." · Reviewed by Greptile

@eaglethrost eaglethrost changed the title fix(mdxish): keep html comments as written when serializing fix(mdxish): keep html comments syntax as written when serializing Nov 18, 2026
@eaglethrost
eaglethrost marked this pull request as ready for review November 18, 2026 04:13
Comment thread processor/compile/index.ts Outdated

// needed only for mdxish
// MDX-ish parses and hides `<!-- -->`, so it stays as written; only MDX needs the JSX comment.
...(mdxish && { html: (node: Html) => node.value }),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if an editor paragraph starts w/ a comment it saves as <!-- x --> more **bold**, which reloads as one html block - bold/links show up as literal text. adding a \n after the comment when it's parent.children[0] fixes it

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's actually the standard markdown behaviour, I don't think adding a \n would work & cause more issues as it'll split the paragraph, move the text after to a new row, and it'll still reload as HTML block in the editor. We'd be modifying the user content, so I'm inclined to just keep the behaviour as is. It should be clear it doesn't really make sense to have text after the comment if it starts the line.

Btw if the comment is in the middle of a paragraph it would be fine.

Comment thread processor/compile/index.ts Outdated

// needed only for mdxish
// MDX-ish parses and hides `<!-- -->`, so it stays as written; only MDX needs the JSX comment.
...(mdxish && { html: (node: Html) => node.value }),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a comment in a table that saves as <Table> (cell w/ a code block, column widths, etc) breaks the table on reload - strict mdx can't parse <!-- so it comes back as raw html w/ literal code fences. I think mdxishTablesToJsx still needs to turn these into {/* */}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yeah, thanks for the catch 🙏

Comment thread processor/compile/index.ts Outdated

// needed only for mdxish
// MDX-ish parses and hides `<!-- -->`, so it stays as written; only MDX needs the JSX comment.
...(mdxish && { html: (node: Html) => node.value }),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

comments inside <Callout>/<Tab> get re-indented on the second save even w/o edits - node.value keeps its leading spaces and the jsx serializer adds more

Suggested change
...(mdxish && { html: (node: Html) => node.value }),
...(mdxish && { html: (node: Html) => node.value.trimStart() }),

Comment thread processor/compile/index.ts Outdated
Comment on lines +42 to +43
// MDX-ish parses and hides `<!-- -->`, so it stays as written; only MDX needs the JSX comment.
...(mdxish && { html: (node: Html) => node.value }),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this overrides html: compatibility on line 35 w/ a copy of the default handler (minus its || '' guard). w/ the fixes above it won't be a one-liner anyway so I'd move it to processor/compile/html.ts + pick the handler once on line 35

@eaglethrost
eaglethrost merged commit 71c24b4 into next Nov 19, 2026
8 checks passed
@eaglethrost
eaglethrost deleted the dimas/rm-19746-investigate-comment-syntax-normalization-and branch November 19, 2026 04:38
rafegoldberg pushed a commit that referenced this pull request Nov 19, 2026
## Version 16.2.4
### 🛠 Fixes & Updates

* **mdxish:** keep html comments syntax as written when serializing ([#1692](#1692)) ([71c24b4](71c24b4)), closes [#1686](#1686)
* **mdxish:** render footnote refs in table ([#1494](#1494)) ([c41296f](c41296f))
* **mdxish:** terminate html flow block when opener has trailing text ([#1495](#1495)) ([a273c3d](a273c3d))

<!--SKIP CI-->
@rafegoldberg

Copy link
Copy Markdown
Collaborator

This PR was released!

🚀 Changes included in v16.2.4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants