docs(readme): reframe positioning and link web benchmark#33
Merged
erweixin merged 2 commits intoerweixin:mainfrom Apr 7, 2026
Merged
docs(readme): reframe positioning and link web benchmark#33erweixin merged 2 commits intoerweixin:mainfrom
erweixin merged 2 commits intoerweixin:mainfrom
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to #30 and #32, addressing the framing problem raised in #31.
What this changes
Rewrites the "Why RaTeX?" comparison table in both
README.mdandREADME.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:
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
Replaced the comparison table with one that adds two honest rows:
headless Chrome/mathjax-node/single binary, no JS runtimePlus an
Output substraterow (DOM tree vs display list) which is where most of RaTeX's "no DOM coupling" advantages actually come from.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.
Linked the new web benchmark page (
demo/benchmark.htmlfrom demo: add RaTeX vs KaTeX web benchmark page #30) alongside the existing live demo and support table.Mirrored everything in
README.zh-CN.mdso the two versions stay in sync.What this PR is not
Architecture,Quick start,Platform targets, etc. are untouched.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.parseoverhead — 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.