From fc4b9f2bf5f1eb5943dce69329f8465f328a56cc Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Fri, 11 Sep 2026 13:55:46 -0600 Subject: [PATCH] docs: refresh Markdown compatibility and measurements --- docs/comparison.md | 4 ++-- docs/core-concepts/parsing.md | 2 +- docs/core-concepts/rendering.md | 2 +- docs/core-concepts/syntax-profile.md | 8 ++++---- docs/guides/performance.md | 4 ++-- docs/guides/testing.md | 6 +++--- docs/overview.md | 2 +- docs/project/faq.md | 2 +- 8 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/comparison.md b/docs/comparison.md index 0201828..6aa5e05 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -52,11 +52,11 @@ These repository benchmarks bundle representative browser entry points from pinn | commonmark.js | 48.1 KB | 39.8 KB | | markdown-it | 52.7 KB | 44.0 KB | -The comparison does not represent equivalent feature sets. It shows the cost of each measured path for this repository’s rendering benchmark. See the generated [size report](../reports/sizes.md) for exact bytes and versions. +The comparison does not represent equivalent feature sets. It shows the cost of each measured path for this repository’s rendering benchmark. See the generated [size report](https://github.com/TanStack/markdown/blob/main/reports/sizes.md) for exact bytes and versions. ## Compatibility accounting -The generated [compatibility report](../reports/conformance.md) tracks matches against all 652 CommonMark 0.31.2 examples after serializer normalization. Every established match is protected individually by the regression suite. The count is accounting, not a conformance claim or a target to maximize. Selected official GFM examples separately cover tables, task lists, and strikethrough. +The generated [compatibility report](https://github.com/TanStack/markdown/blob/main/reports/conformance.md) tracks matches against all 652 CommonMark 0.31.2 examples after serializer normalization. Every established match is protected individually by the regression suite. The count is accounting, not a conformance claim or a target to maximize. Selected official GFM examples separately cover tables, task lists, and strikethrough. Use [commonmark.js](https://github.com/commonmark/commonmark.js), micromark, or a unified pipeline when exact specification behavior is a requirement. Use TanStack Markdown when your corpus fits the [documented profile](core-concepts/syntax-profile) and the smaller, controlled renderer is the better product tradeoff. diff --git a/docs/core-concepts/parsing.md b/docs/core-concepts/parsing.md index 3c06d74..31fbd2e 100644 --- a/docs/core-concepts/parsing.md +++ b/docs/core-concepts/parsing.md @@ -52,7 +52,7 @@ The second callback argument is the zero-based normalized parser line index. It ## Definitions and footnotes -Link definitions are collected before block parsing and resolved case-insensitively. Footnotes are emitted in first-reference order, with collision-safe IDs and back-reference counts. +Link definitions are collected before block parsing. Reference labels are matched case-insensitively with whitespace collapsed, and the first definition wins when labels repeat. Footnotes are emitted in first-reference order, with collision-safe IDs and back-reference counts. The `references`, `footnotes`, `footnoteOrder`, and `footnoteCounts` fields in `ParseOptions` carry parser state through nested parsing. Most consumers should leave them unset. diff --git a/docs/core-concepts/rendering.md b/docs/core-concepts/rendering.md index b353f35..bcf8f29 100644 --- a/docs/core-concepts/rendering.md +++ b/docs/core-concepts/rendering.md @@ -37,7 +37,7 @@ Renderer-specific boundaries are excluded from this guarantee: ## Lists -Tight lists render paragraph content directly under `
  • `. Loose lists preserve `

    ` wrappers. Task-list checkboxes stay inline with their labels in either form. +Tight lists render paragraph content directly under `

  • `. Loose lists preserve `

    ` wrappers. Task-list checkboxes stay inline with their labels in either form. A loose nested list does not make its parent list loose, and ordered lists preserve a starting value of zero. ## Code blocks diff --git a/docs/core-concepts/syntax-profile.md b/docs/core-concepts/syntax-profile.md index f5ae157..2e378e5 100644 --- a/docs/core-concepts/syntax-profile.md +++ b/docs/core-concepts/syntax-profile.md @@ -15,8 +15,8 @@ TanStack Markdown implements a documented subset aimed at repository-authored bl | Fenced code blocks | Yes | Backtick and tilde fences, language and docs metadata | | Blockquotes | Yes | Nested parsing with a bounded depth | | Unordered lists | Yes | Tight, loose, nested, and task items | -| Ordered lists | Yes | `.` and `)` markers, custom starts, tight and loose items | -| Tables | Yes | Header delimiter and left/center/right alignment | +| Ordered lists | Yes | `.` and `)` markers, custom starts including zero, tight and loose items | +| Tables | Yes | Header delimiter, alignment, and escaped pipes in cells | | Thematic breaks | Yes | Hyphen, asterisk, and underscore forms | | Frontmatter extraction | Yes | Leading `---` block, enabled by default | | Footnotes | Yes | Definition order follows first reference | @@ -30,9 +30,9 @@ TanStack Markdown implements a documented subset aimed at repository-authored bl | --- | :---: | --- | | Emphasis and strong | Yes | Natural prose patterns; not every pathological delimiter case | | Strikethrough | Yes | GFM `~~text~~` and legacy TanStack `~text~`; numeric approximations stay literal | -| Inline code | Yes | Backtick spans | +| Inline code | Yes | Matching backtick runs; internal spaces and tabs are preserved | | Inline links and images | Yes | Unsafe URL protocols are removed | -| Reference links and images | Yes | Full and collapsed forms used by the maintained corpus | +| Reference links and images | Yes | Full, collapsed, and shortcut forms; normalized reference labels | | Hard breaks | Yes | Backslash before a newline | | Raw inline HTML | Opt-in | Requires `allowHtml: true` | | Autolink literals | No | Write an explicit link | diff --git a/docs/guides/performance.md b/docs/guides/performance.md index da533cb..ea5dfaa 100644 --- a/docs/guides/performance.md +++ b/docs/guides/performance.md @@ -21,9 +21,9 @@ The generated browser bundle report records: | docs preset | 2.3 KB | 2.1 KB | | callouts extension | 0.3 KB | 0.3 KB | -Framework runtimes are externalized from their adapters, and the highlighter measurement uses only a callback stub. Exact generated bytes live in the [size report](../../reports/sizes.md). +Framework runtimes are externalized from their adapters, and the highlighter measurement uses only a callback stub. Exact generated bytes live in the [size report](https://github.com/TanStack/markdown/blob/main/reports/sizes.md). -The maintained benchmark records parse, pre-parsed rendering, parse-and-render, external-highlighter, and progressive AI-response paths against pinned comparison packages. Timings vary by runtime, CPU, fixture shape, and dependency version, so the generated [benchmark report](../../reports/benchmarks.md) is the only source of current CPU results. +The maintained benchmark records parse, pre-parsed rendering, parse-and-render, external-highlighter, and progressive AI-response paths against pinned comparison packages. Timings vary by runtime, CPU, fixture shape, and dependency version, so the generated [benchmark report](https://github.com/TanStack/markdown/blob/main/reports/benchmarks.md) is the only source of current CPU results. ## Use the narrow entry point diff --git a/docs/guides/testing.md b/docs/guides/testing.md index 1e56b27..9837fe4 100644 --- a/docs/guides/testing.md +++ b/docs/guides/testing.md @@ -38,8 +38,8 @@ Both audits parse every Markdown file twice with the docs profile, verify determ The external audit runs in CI and fails on parser errors, nondeterminism, or any unexplained target-profile content difference. The local TanStack audit enforces the same rule when the sibling repositories are available. -- [TanStack repository corpus](../../reports/tanstack-corpus.md) -- [External docs and blogs corpus](../../reports/external-corpus.md) +- [TanStack repository corpus](https://github.com/TanStack/markdown/blob/main/reports/tanstack-corpus.md) +- [External docs and blogs corpus](https://github.com/TanStack/markdown/blob/main/reports/external-corpus.md) ### Triage policy @@ -56,7 +56,7 @@ A syntax rule enters the profile only when real target content needs it, the beh pnpm run conformance ``` -The command compares output against CommonMark 0.31.2 examples, preserves every established match as a regression baseline, and updates [the generated report](../../reports/conformance.md). It is not a claim of full conformance. +The command compares output against CommonMark 0.31.2 examples, preserves every established match as a regression baseline, and updates [the generated report](https://github.com/TanStack/markdown/blob/main/reports/conformance.md). It is not a claim of full conformance. Selected official GFM examples separately cover tables, task lists, and strikethrough in the supported profile. diff --git a/docs/overview.md b/docs/overview.md index bba17b4..152b95e 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -31,7 +31,7 @@ TanStack Markdown spends its complexity budget on that path. It deliberately doe ### Small entry points -Current minified browser bundles are 4.9 KB gzip for the parser and 6.7 KB for HTML rendering or either UI adapter with its framework runtime externalized. The generated [bundle report](../reports/sizes.md) is the source of truth. +Current minified browser bundles are 4.9 KB gzip for the parser, 6.7 KB for HTML rendering, and 6.6 KB for either UI adapter with its framework runtime externalized. The generated [bundle report](https://github.com/TanStack/markdown/blob/main/reports/sizes.md) is the source of truth. ### Parse once, render many diff --git a/docs/project/faq.md b/docs/project/faq.md index 5037953..e254fdc 100644 --- a/docs/project/faq.md +++ b/docs/project/faq.md @@ -6,7 +6,7 @@ title: FAQ ## Is TanStack Markdown CommonMark compliant? -No. It continuously measures CommonMark behavior and preserves established matches, but full conformance is not the product goal. The current generated report matches 348 of 652 CommonMark 0.31.2 examples after output normalization. +No. It continuously measures CommonMark behavior and preserves established matches, but full conformance is not the product goal. The [generated compatibility report](https://github.com/TanStack/markdown/blob/main/reports/conformance.md) records 403 of 652 CommonMark 0.31.2 examples matching after output normalization in v0.0.14. ## Is it GFM compliant?