Skip to content

Parsing errors and content lost when saving Markdown #525

Open

Description

@onmax

These examples show parsing errors and content lost when Comark saves Markdown. Cases 1–31 were reproduced on Comark 0.8.1 and main at b17f456; cases 32–36 on 0.8.1 and main at 41409df.

Checked again on main at a708f09 (2026-11-16): cases 1–7, 11 and 37 are fixed, and so are the seven round-trip PRs at the end of the list. Keep a case unchecked until its fix is merged and verified. Each linked PR is a proposed fix; cases without a fix link have no matching open PR found. Playground links open the playground on comark.dev (#526). Open the Formatted tab to see what changes when the Markdown is saved.

Markdown loses content when saved

References: GFM task lists and CommonMark fenced code blocks. Cases 2–4 concern Comark components.

  • 1. Task items with nested blocks lose their text and indent following blocks as code. playground · Fixed: #527 (merged) · Related: #537 (merged, component after a list gets indented)
  • 2. ::table{src="data.csv"} is saved as an empty table. playground · Fixed: #527 (merged)
  • 3. :comment[a note] disappears. playground · Fixed: #527 (merged)
  • 4. :math[x] becomes $x$ instead of staying a component. playground · Fixed: #527 (merged)
  • 5. Fenced code loses trailing blank lines and spaces. playground · Fixed: #527 (merged)

Text moves out of HTML tags

Also reported in #505. Reference: CommonMark raw HTML.

HTML parsing

References: CommonMark raw HTML, HTML blocks, soft line breaks, and browser HTML tree construction. For malformed HTML, the expected output follows how browsers parse it.

  • 8. Newlines inside HTML disappear, joining words and script lines. playground
  • 9. An HTML block with JSX-style attributes, such as <div style={{a: 1}}>, becomes literal text instead of remaining HTML. playground · Fix: #530 (open)
  • 10. An HTML tag left open inside a paragraph swallows later blocks. playground · Fix: #530 (open)
  • 11. </br> disappears instead of producing the line break browsers give it. playground · Fixed: #538 (merged) · Also in #530 (open)
  • 12. A second <p> nests inside the first instead of closing it. playground · Fix: #530 (open)
  • 13. Images, <br>, and custom elements inside HTML split or lose their paragraph. playground · Fix: #530 (open) · Related: #535 (merged, br serialization)
  • 14. An HTML tag left open in a list changes the text order and adds a <fragment> element. playground · Fix: #530 (open)
  • 15. Standalone HTML comments gain a <p> wrapper. Comark also fails to recognize <!--- ---> as a comment. playground · Fix: #530 (open)
  • 16. Raw <pre><code> content renders its tags and entities literally. playground · Fix: #530 (open)
  • 17. autoUnwrap removes a <p> written by the author and moves its attributes onto the parent. playground · Fix: #530 (open)
  • 18. Duplicate HTML attributes keep the last value rather than the first. playground · Fix: #530 (open)
  • 19. html({ markdown: false }) leaves character references encoded in HTML text. · Fix: #530 (open) · API repro

Markdown structure and autolinks

References: CommonMark images, ATX headings, fenced code blocks, block quotes, list items, GFM tables, and GFM autolinks.

  • 20. Decorative Markdown images lose alt="". playground
  • 21. Empty ATX headings disappear. playground
  • 22. A code block's language disappears when it is written as {x}. playground
  • 23. Bare URLs and emails differ from GFM for .dev addresses, underscores in hosts, non-numeric ports, emphasis around URLs, and percent-encoded link text. playground · example 2 · example 3 · example 4
  • 24. markdown-exit parses some indented blockquote lines, code fences inside lists, and table rows inside list items differently from the spec. playground · example 2 · example 3

Comark attributes and frontmatter

CommonMark does not define these Comark extensions: attributes and frontmatter.

  • 25. An unclosed attribute group, such as a {b c, deletes the rest of the line. playground · Fix: #570 (open) · Related: #534 (closed, kept closed invalid brace groups as text; the unclosed case was not covered)
  • 26. --- x closes frontmatter too early. A leading byte order mark stops Comark from finding frontmatter. playground · example 2 · Fix: #570 (open)
  • 27. Invalid YAML frontmatter makes parseMarkdown throw. Report the invalid YAML without losing the document. playground · Fix: #570 (open)

Callouts and footnotes

CommonMark does not define these extensions. References: GitHub alerts and Comark footnotes.

Code changes when rendered, and large paragraphs crash

Reference: CommonMark fenced code blocks. Case 30 uses @comark/html and needs the API reproduction below. The playground uses the Vue renderer.

  • 30. @comark/html adds indentation inside nested code and escapes > in <style>/<script>, changing their content. · API repro
  • 31. A paragraph with many children throws RangeError: parseMarkdown("https://x.com/a ".repeat(65536)). playground

Other round-trip fixes

These PRs fixed parseMarkdown → renderMarkdown losses found in the Nuxt docs. They don't match a case above.

  • #501 Keep inline HTML comments inside their paragraph (merged)
  • #544 Don't end a paragraph after an inline comment (merged)
  • #543 Separate a block comment from the paragraph before it in a list item (merged)
  • #536 Keep raw HTML attribute names and values verbatim (merged)
  • #540 Skip $ metadata when rendering Markdown attributes (merged)
  • #541 Write edge non-breaking spaces in table cells as &nbsp; (merged)
  • #542 Don't rewrite a trailing table row that contains a dash (merged)

Found by moving markdown-it and marked projects to Comark

These came from running markdown-it and marked projects through Comark: the 100 most-starred repositories using each library. References: CommonMark images and Comark's markdown-it plugin docs, which list mark and insert among the plugins that work. Cases 34–36 load markdown-it plugins, which the playground can't, so they're in the API examples below.

  • 32. Text that starts with <!-- becomes a comment even when it isn't HTML: &lt;!-- shown --&gt; text renders <!-- shown --> and loses the word text. playground
  • 33. An image's alt keeps its Markdown: ![[x](u) *y*](a.png) gets alt="[x](u) *y*", where CommonMark uses the plain text, alt="x y". playground
  • 34. Tokens a markdown-it plugin adds lose their element when the tree builder doesn't know them. markdown-it-mark's ==m== and markdown-it-ins' ++i++ render plain text, and so does the ==highlight== rule in the docs' own example; sub and sup work. · API repro
  • 35. Attributes a markdown-it plugin sets on a code block are dropped: markdown-it-attrs sets class="cls" on the fence token for a fence opened with ```js {.cls}, and the pre node doesn't have it. · API repro
  • 36. An html_block token inside a heading's inline tokens is dropped, so markdown-it-anchor's permalink symbol disappears and the heading ends in an empty <a class="header-anchor">. · API repro

Examples that need the API

The playground cannot set html({ markdown: false }), use @comark/html, or load custom markdown-it plugins. Cases 19, 30, and 34–36 need these API examples.

Cases 30, 19, 31, and 34–36
import { parseMarkdown } from "comark";
import { renderHtmlFromDocument } from "@comark/html";
import html from "comark/plugins/html";

// 30: Code indentation changes, and the CSS selector becomes a &gt; b.
console.log(await renderHtmlFromDocument(await parseMarkdown(
  "- x\n\n  ```\n  a\n    b\n  ```\n\n<style>\na > b {}\n</style>"
)));

// 19: Expected HTML text is "<b> & x", not "&lt;b&gt; &amp; x".
console.log((await parseMarkdown("<div>\n&lt;b&gt; &amp; x\n</div>", {
  plugins: [html({ markdown: false })]
})).nodes);

// 31: RangeError: Maximum call stack size exceeded.
await parseMarkdown("https://x.com/a ".repeat(65536));
import { renderHtml } from "@comark/html";
import { defineComarkPlugin } from "comark/parse";
import mark from "markdown-it-mark";
import attrs from "markdown-it-attrs";
import anchor from "markdown-it-anchor";

const plugin = (name, ...use) =>
  defineComarkPlugin(() => ({ name, markdownItPlugins: [(md) => md.use(...use)] }))();

// 34: Expected <p><mark>m</mark></p>; renders <p>m</p>.
console.log(await renderHtml("==m==", { plugins: [plugin("mark", mark)] }));

// 35: Expected class="cls" on the code block; it has only class="language-js".
console.log(await renderHtml("```js {.cls}\nx\n```", { plugins: [plugin("attrs", attrs)] }));

// 36: Expected § inside the heading's anchor; the anchor is empty.
console.log(await renderHtml("# Title", {
  plugins: [plugin("anchor", anchor, { permalink: true, permalinkSymbol: "§" })]
}));

Runnable checks for all cases.

HTML attribute entity decoding

  • 37. Raw HTML attributes decode legacy character references using body-text rules, so href="https://example.com/?x=1&copy=2" becomes https://example.com/?x=1©=2. Expected: keep the literal &copy=2 in both single- and double-quoted values. Non-URL attributes such as title="x=1&copy=2" change too. Fixed: #511 (merged). This happens during parsing, before rendering. fix(render): keep raw HTML attribute names + values verbatim #536 covers writing attribute names and values back to Markdown, and does not change this decoder. playground, all quote variants and controls. Open the AST tab to inspect the parsed values.

parseHtmlAttributes calls entities.decodeHTML, which uses body-text rules. Attribute rules use decodeHTMLAttribute and leave a semicolonless named reference alone when the next character is = or an ASCII alphanumeric. Reference: HTML character references in attributes.

Minimal API repro, with comark@0.8.1 and entities@8.1.0 installed:

import { parseMarkdown } from "comark";
import { decodeHTMLAttribute } from "entities";

for (const quote of ['"', "'"]) {
  for (const [tag, attr, value] of [
    ["a", "href", "https://example.com/?x=1&copy=2"],
    ["span", "title", "x=1&copy=2"],
    ["a", "href", "https://example.com/?x=1&amp;copy=2"],
    ["span", "title", "&amp;lt;"],
    ["a", "href", "https://example.com/?a=1&amp;b=2"],
    ["span", "title", "&copy;"],
  ]) {
    const { nodes } = await parseMarkdown(
      `text <${tag} ${attr}=${quote}${value}${quote}>x</${tag}> tail`
    );
    const actual = nodes[0][3][1][attr];
    console.log({ value, expected: decodeHTMLAttribute(value), actual });
    console.log({ afterConsumerDecode: decodeHTMLAttribute(actual) });
  }
}

For both quote styles, the first two inputs lose &copy and gain ©. The &amp;copy=2 control correctly becomes &copy=2. &amp;lt; correctly becomes &lt; in Comark, but a consumer decoding the parsed value again gets <. Comark itself decodes once. The valid &amp; reference correctly becomes &, and &copy; correctly becomes ©, so preserving every entity verbatim is not the expected parser behavior.

Confirmed on the published 0.8.1 package and current main at 77c7038641b65132cb5f25e102bb6ff4edad7dd5, running the parser source via jiti. Both give the same results for all six inputs with both quote styles. Node 24.21.0, entities 8.1.0, markdown-exit 1.3.0, Linux.

Downstream workaround: vite-hub/vitehub#3322 escapes attribute ampersands before Comark decodes them, then applies decodeHTMLAttribute once in the consumer.

Activity

  1. changed the title [-]renderMarkdown round trip drops or changes content: task items, components named table/comment/math, trailing blank lines, callout titles[/-] [+]Markdown Comark gets wrong: renderMarkdown round-trip losses, and parsing differences from CommonMark/GFM[/+] on Oct 31, 2026
  2. changed the title [-]Markdown Comark gets wrong: renderMarkdown round-trip losses, and parsing differences from CommonMark/GFM[/-] [+]Track Comark parsing and Markdown round-trip cases by category and PR[/+] on Nov 1, 2026
  3. changed the title [-]Track Comark parsing and Markdown round-trip cases by category and PR[/-] [+]Parsing errors and content lost when saving Markdown[/+] on Nov 1, 2026
  4. onmax commented on Nov 2, 2026

    @onmax
    ContributorAuthor

    hwy @farnabaz , I have updated this issue over the weekend.

    I opened #530 to fix the "HTML parsing". But seeing daniels work, not sure if you prefer independent prs with specific issue for each.

    I am afraid I might be spamming too many PRs so I decide to stop first and give you sometime to catch up.

    There is no rush 🚀

  5. farnabaz commented on Nov 2, 2026

    @farnabaz
    Collaborator

    @onmax Thanks you for your effort
    I don't mind having a medium size PRs with multiple fix in it 🙂

    I am afraid I might be spamming too many PRs so I decide to stop first and give you sometime to catch up.

    Thats nice of you

    One thing that I would appreciate is to have clear spec markdowns inside SPEC directory, those are very easy to read for me and good way to freeze behavior. Having a test via vitest also good, but is is harder to read as inputs are markdown.

  6. onmax commented on Nov 2, 2026

    @onmax
    ContributorAuthor

    Thanks! I'll move #530's cases into `SPEC/HTML and keep vitest clean

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions