Performance#

Copy as MarkdownView Markdown

This page tracks benchmark results, bundle-size checks, and the optimizations that affect shipped output. Architecture and package pages should describe boundaries and APIs; measured performance belongs here.

For allocation and span-level investigation while developing parser or renderer changes, use Profiling Mode. Profiling answers "where is the work happening?" Benchmarking answers "how fast is this workload?"

What We Measure#

Ox Content has four performance surfaces, all reported on pull requests:

• Runtime throughput for Markdown parsing and rendering.
• Fixture production build time.
• Static output weight for generated sites, including gzip size and rendered HTML gzip.
• Initial request count for index.html and local critical-path assets.

Runtime matters for CLIs, dev servers, editor integrations, and batch builds. Output weight matters for documentation sites because generated HTML, CSS, and JS are what users fetch on every navigation. Absolute ceilings live in tools/benchmarks/perf-budgets.json. Relative base/head deltas still use the PR Benchmark comment.

Out of scope#

These are intentionally not gated by the budget file:

• Host-absolute ops/sec on developer laptops. Use the published relative ordering; the floors are for the Blacksmith runner class.
• Competitor app sizes (VitePress, Astro) as fail-the-build ceilings.
• Full docs-site output (docs/dist), OG image binaries, and fetched fonts.
• vp run build:npm wall time. The fixture buildMs field is the build-time budget; the package graph is not timed by this harness.
• Isolated search, theme, embed, Code Play, or MDX island payloads. The default fixture does not enable those features, so they stay out of the default-shell number.

Runtime Snapshot#

Ox Content is positioned both as a document generator and as a high-performance Markdown toolkit. The numbers below focus on the Markdown engine side.

Speed is only half of a fair comparison: Markdown engines differ in how much of CommonMark they implement, and some deliberately trade spec coverage for throughput. Every row therefore carries a measured CommonMark conformance rate next to its speed, so a faster engine that skips spec behavior is visible as such rather than simply ranking higher. See CommonMark Conformance for how Ox Content scores and how the rate is measured.

Benchmark sweep generated on 2026-08-30 (median of 7 runs). Numbers track the host machine; the relative ordering between engines is the stable signal. Regenerated by tools/scripts/render-benchmark-tables.mjs.

Environment: runner blacksmith-32vcpu-ubuntu-2404, Node v26.8.1, Bun 1.3.14, CPU AMD EPYC, 32 logical cores.

CommonMark column: share of the 652 CommonMark 0.31.2 spec examples an engine renders correctly, measured by tools/benchmarks/commonmark-conformance/run.mjs. Each engine runs in the most spec-faithful configuration it exposes, and both sides of the comparison pass through the conformance suite's HTML normalizer, so engines are ranked by behavior rather than by markup spelling.

Parse Only (48.7 KB)#

Parse + Render (48.7 KB)#

Parse Only (~1 MB)#

Parse + Render (~1 MB)#

The tables above are regenerated from a clean Blacksmith 32 vCPU CI environment by the Benchmark docs workflow; run OX_CONTENT_BENCHMARK_RUNS=7 vp run bench:docs to refresh them locally. Absolute ops/sec track the host (earlier sweeps on faster hardware report higher numbers); the relative ordering between engines is the stable signal.

On the 48.7 KB document the boundary-free native row leads the fastest other engine (pulldown-cmark) by ~1.6x on parse-only and ~1.2x on parse+render; at ~1 MB those leads are ~1.5x and ~1.2x. On parse+render the second row is now @ox-content/napi rather than a third-party engine, so the N-API boundary — not the engine — is what separates the top two rows there. The JavaScript-facing @ox-content/napi row is 4.0–5.1x faster than the two TypeScript renderers on parse-only and 7.1–12.1x faster on parse+render. At ~1 MB those N-API leads grow to 7.7–8.7x and 11.4–12.0x respectively, while the native pipeline sustains 267–370 MB/s. The @mizchi/markdown rows are split by JS, Wasm, and native runtime so package-boundary and native-build costs stay visible, while the unified/remark pipeline stays at ~1 op/sec in both ~1 MB tables and micromark measures ~1 op/sec on parse+render.

The runtime sweep covers more than the tables above. The harness also runs small and medium Markdown inputs, an async parse+render target for the N-API package (so PR checks can catch JavaScript-boundary overhead regressions), and an optional Bun.markdown comparison when the harness is run under Bun.

The TypeScript renderer comparisons use each package's public default API. @tanstack/markdown is measured through parseMarkdown for parse-only and renderHtml for parse+render. markdown-it-ts reuses one initialized instance and measures parse and render, matching the existing markdown-it setup. Parser construction, module loading, and benchmark warmup happen outside the timed loop; each parse+render operation starts from the same Markdown string.

CommonMark Conformance#

Ox Content targets full CommonMark conformance. The engine is checked against the vendored CommonMark 0.31.2 specification on every CI run, not only when the benchmark tables are refreshed:

• Core profile: 652 / 652 examples. cargo test -p ox_content_renderer --test spec_commonmark fails both when a passing example regresses and when a recorded failure starts passing, so the baseline cannot quietly drift.
• GFM profile: 649 / 652 examples. The three differences are spec examples 608, 611, and 612, where the GFM autolink extension deliberately linkifies bare URLs and emails that plain CommonMark leaves as text. They are listed in crates/ox_content_renderer/tests/spec_fixtures/commonmark-known-failures.txt.
• GFM extensions: every example in the GitHub Flavored Markdown 0.29-gfm spec sections for tables, task lists, strikethrough, autolinks, and disallowed raw HTML, driven by spec_gfm.rs.

Extensions beyond CommonMark — GFM tables, task lists, strikethrough, footnotes, and the built-in embeds — are opt-out rather than opt-in, so a document that uses none of them conforms to the specification under the normalization rule described below (ox-content adds slug id attributes to headings, so the HTML is not byte-identical to the spec's). Markdown Baseline lists each toggle.

Reading the CommonMark Column#

The rate beside each engine is measured, not claimed. tools/benchmarks/commonmark-conformance/run.mjs renders all 652 spec examples with every engine in the tables and compares the output to the specification.

Two choices make that comparison fair, and both matter when reading the numbers:

• Each engine runs in the most spec-faithful configuration it exposes, not in its benchmark defaults. markdown-it and markdown-it-ts use their commonmark presets, micromark and remark-html are told to pass raw HTML through instead of escaping it, and md4w runs with parseFlags: 0. Judging an engine by a default preset that enables GFM extensions would measure the preset rather than the engine. The @mizchi/markdown JS, Wasm, and native rows disable their default autolink and tagfilter extensions for this column. Engines that expose no such mode — marked, md4x, @tanstack/markdown — are scored as they ship.
• Both sides pass through the conformance suite's HTML normalizer, so differences that do not change how a document renders (entity spelling, attribute order, <br /> vs <br>, whitespace between block tags) are not counted as conformance gaps. Without it the table would rank engines by markup spelling: ox-content scores 82.5% under byte-exact comparison purely because it adds slug id attributes to headings.

The comparison is symmetric — pulldown-cmark, an independent Rust implementation unrelated to ox-content, also scores 100% — so the normalizer is not tuned to any one engine.

Two rows are the same engine at different layers. ox-content (native) is the core profile at 100%; @ox-content/napi scores 99.5% because its defaults enable the bare-URL autolinking builtin, which linkifies examples 602, 608, and 611. Pass autolinkUrls: false to turn it off.

Regenerate the results with:

node tools/benchmarks/commonmark-conformance/run.mjs --json tools/benchmarks/commonmark-conformance/results.json

CJK Emphasis#

CommonMark's emphasis rules do not recognize ** placed immediately inside CJK punctuation, so A**強調。**B renders as literal text rather than bold. This affects every spec-conformant engine — it is a property of the specification's left/right-flanking delimiter rules, not an implementation gap. Emphasis that merely sits next to CJK characters — これは**重要**です。 — is allowed by the specification and works everywhere.

Ox Content ships an opt-in deviation for it. cjkEmphasis classifies East Asian punctuation as an ordinary character when deciding whether a delimiter run may open or close, which lets those runs pair; halfwidth ASCII punctuation is left alone, so Latin documents parse identically. It is off by default, which is what keeps the 652/652 figure above true of the shipped default. See CJK Emphasis.

Bundle Size#

The bundle-size benchmark builds representative docs applications and measures the generated production output. It reports:

• Total bytes across the generated output directory.
• Gzipped bytes for JS, CSS, HTML, and JSON assets.
• File count in the output directory.
• Estimated initial requests for index.html and local assets referenced from HTML or CSS.

Latest Blacksmith fixture sweep on 2026-08-26 (blacksmith-32vcpu-ubuntu-2404, Node v26.7.0), taken from PR Benchmark comments such as #1001 and #1005.

ox-content (bare) is the no-JS baseline. ox-content includes the built-in docs shell. ox-content + Vue adds framework island support. VitePress rows use the same benchmark content so the comparison is focused on generated output shape rather than authoring content.

Bundle-size comparisons are intentionally reported beside request count. A smaller gzip number is not always better if it creates too many blocking requests; a larger shared chunk can be preferable when it removes repeated bytes from every generated page and is cacheable across navigation.

Chunk Optimization#

The SSG pipeline first renders complete HTML pages, then extracts shared assets after all pages are known. The TypeScript plugin calls the Rust-backed externalizeSsgAssets implementation, which rewrites each generated page and writes hashed assets under assets/.

The optimizer keeps the rules conservative:

• Identical CSS and JS content is deduplicated by content, then emitted once with a content hash in the filename.
• Core CSS sections such as base and footer styles are linked as a shared ox-content-core-*.css file.
• Theme CSS stays inline when it is small or when it contains relative url(...) references, so path resolution does not change.
• Search payload code is split from the main boot script into a separate ox-content-search-*.js chunk when the generated script contains the search placeholder.
• Generated scripts are emitted with defer, and public asset paths honor the configured site base.

The goal is not to split every feature into a separate file. The docs shell is small enough that excessive chunking can increase startup work. The current policy favors stable shared chunks for repeated bytes and avoids moving content when doing so would create path-resolution risk or extra request overhead.

PR Regression Gate#

Pull requests run the benchmark workflow against both the base commit and the head commit on blacksmith-32vcpu-ubuntu-2404. The workflow posts one report with runtime, competitive snapshot, environment, bundle-size, and budget sections.

Runtime rows compare the large benchmark target for @ox-content/napi and @ox-content/napi (async). Changes within +/-5% are treated as noise, and the check fails when head throughput is more than 10% slower than base.

The competitive snapshot is not a gate. It uses the head commit to show the target package against the next fastest comparison package for the same large input corpus.

Bundle rows compare gzipped output for each successful benchmark app. The check fails when gzipped size grows by more than 5%. Head measurements also fail when they exceed tools/benchmarks/perf-budgets.json. Maintainers can intentionally accept either failure with the benchmark-regression-accepted PR label.

Area Audit#

Each major surface has a measured baseline and either a target or an explicit no-op. Numbers are from the 2026-08-26 Blacksmith reports cited above, not from a local laptop run.

Reproduce#

Run the JavaScript benchmark harness from the repository root:

node tools/benchmarks/bundle-size/parse-benchmark.mjs

The benchmark includes @tanstack/markdown, markdown-it-ts, md4w (md4c), and md4x (napi) by default, and adds Bun.markdown.html automatically when bun is available.

Run the bundle-size benchmark from the repository root:

node tools/benchmarks/bundle-size/measure.mjs

For a faster local rerun after dependencies are installed, use:

node tools/benchmarks/bundle-size/measure.mjs --skip-install

Write JSON for the budget checker, and optionally run the dedicated build-time sweep (also from the repository root):

node tools/benchmarks/bundle-size/measure.mjs --json /tmp/bundle.json
node tools/benchmarks/bundle-size/build-time-benchmark.mjs --json /tmp/build.json
node tools/benchmarks/bundle-size/check-budgets.mjs --bundle /tmp/bundle.json --build /tmp/build.json

For Rust-side parser benchmarks, use:

cargo bench -p ox_content_parser

For real-world Markdown corpus benchmarks, populate the optional corpus first:

node tools/scripts/fetch-bench-corpus.mjs
cargo bench -p ox_content_parser --bench corpus

For N-API transfer-format micro-benchmarks, see @ox-content/napi.