Skip to content

docs(readme): reframe positioning and link web benchmark#33

Merged
erweixin merged 2 commits intoerweixin:mainfrom
EurFelux:docs/readme-positioning
Apr 7, 2026
Merged

docs(readme): reframe positioning and link web benchmark#33
erweixin merged 2 commits intoerweixin:mainfrom
EurFelux:docs/readme-positioning

Conversation

@EurFelux
Copy link
Copy Markdown
Contributor

@EurFelux EurFelux commented Apr 7, 2026

Companion to #30 and #32, addressing the framing problem raised in #31.

What this changes

Rewrites the "Why RaTeX?" comparison table in both README.md and README.zh-CN.md. Nothing else in the README is touched, so the diff is small and easy to revert.

Why

The current table sits RaTeX next to KaTeX/MathJax on a single set of axes (bundle size, runtime, syntax coverage), which accidentally implies they're alternatives at the same layer of abstraction. They aren't:

  • KaTeX is a web component. It runs in V8, outputs DOM, and on the web specifically it's been JIT-optimized for a decade. On its home turf it's excellent and hard to beat.
  • RaTeX is a rendering primitive. Its real contribution isn't "faster KaTeX on the web" — it's being the only KaTeX-compatible engine that runs natively on iOS, Android, Flutter, server-side, and SVG, with byte-identical output across all of them.

On every non-web target, KaTeX/MathJax simply aren't options without hosting a WebView or shelling out to headless Chrome — exactly the things RaTeX exists to avoid. The current table doesn't surface that asymmetry, so a reader skimming it walks away thinking "0 kB JS vs 280 kB JS, ok" and misses the actual story.

The benchmark in #30 makes this concrete from the other direction: on the web, parse-stage RaTeX is roughly comparable to KaTeX (and after #32 even closer), with most of the residual gap living in wasm-bindgen's FFI boundary. So leading with web bundle size is exactly the framing where RaTeX looks weakest. The framing where it looks strongest — and where it's accurate — is "the only engine that gives you the same math renderer on every surface your product touches."

Concrete edits

  1. Replaced the comparison table with one that adds two honest rows:

    • Surfaces it runs on — exposes that KaTeX/MathJax are web-only*
    • Server-side renderingheadless Chrome / mathjax-node / single binary, no JS runtime

    Plus an Output substrate row (DOM tree vs display list) which is where most of RaTeX's "no DOM coupling" advantages actually come from.

  2. Added a short qualifier paragraph acknowledging KaTeX is still the right call for web-only projects, so the framing is calibrated rather than boastful. This is important — overclaiming would be worse than the current understatement.

  3. Linked the new web benchmark page (demo/benchmark.html from demo: add RaTeX vs KaTeX web benchmark page #30) alongside the existing live demo and support table.

  4. Mirrored everything in README.zh-CN.md so the two versions stay in sync.

What this PR is not

  • Not rewriting the rest of the README — Architecture, Quick start, Platform targets, etc. are untouched.
  • Not making any performance claims I can't back up with the benchmark in demo: add RaTeX vs KaTeX web benchmark page #30.
  • Not removing anything substantive — every fact in the original table is still in the new one.

Happy to iterate on tone or wording if any of this comes off too strong, or revert specific rows if you'd rather a more conservative edit. The intent is just to stop the table from accidentally selling RaTeX short.

Refs: #31, #30, #32


Update: also default the web benchmark to Full render

Added one small commit (demo/benchmark.html) that flips the default stage in the benchmark page from Parse + layout (no draw) to Full render (with draw), and reorders the dropdown so Full render is listed first.

Reason: parse-only is the sub-stage where RaTeX is currently weakest (the residual gap is FFI/JSON.parse overhead — see #32 for the analysis), and it is also not what anyone actually does end-to-end. A first-time visitor landing on the benchmark page shouldnt see the most pessimistic slice of the pipeline by default — they should see the realistic full path, which is where RaTeX wins. Parse-only stays available for anyone diagnosing the boundary specifically.

This is in the same spirit as the README reframing in this PR: stop accidentally leading with the framing where RaTeX looks weakest.

EurFelux added 2 commits April 7, 2026 16:28
Update the "Why RaTeX?" comparison so it reflects RaTeX's actual scope
rather than implying it competes with KaTeX/MathJax on a single web-only
axis. The original table compared bundle size and runtime as if RaTeX
were a faster KaTeX, which undersells its real contribution: being the
only KaTeX-compatible engine that runs natively on iOS, Android,
Flutter, server-side, and SVG — surfaces where KaTeX/MathJax aren't
options without hosting a WebView or headless browser.

- Add "Surfaces it runs on" and "Server-side rendering" rows that
  expose the asymmetry honestly.
- Add a short qualifier acknowledging KaTeX is still the right call for
  web-only projects, so the framing is calibrated rather than boastful.
- Link the new web benchmark page alongside the live demo.
- Mirror the same edits in README.zh-CN.md.

Refs: erweixin#31
Full render is the realistic end-to-end path and the one where RaTeX
wins. Parse-only is still useful for diagnosing the FFI/serialize
boundary but shouldn't be what a first-time visitor sees by default —
that view shows RaTeX's weakest sub-stage in isolation.
@erweixin erweixin merged commit 43a23e9 into erweixin:main Apr 7, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants