markdown-it-ts

A TypeScript-first Markdown parser and renderer compatible with the markdown-it public API for common plugin patterns, with streaming/incremental parsing and async render.

English | 简体中文

Quick links: Docs index · Stream optimization · Performance report · Compatibility report

Runtime note

markdown-it-ts is ESM-only and requires Node.js >= 18.

import MarkdownIt from 'markdown-it-ts'

In CommonJS projects, use dynamic import inside an async function:

async function main() {
  const { default: MarkdownIt } = await import('markdown-it-ts')

  const md = MarkdownIt()
  console.log(md.render('# ok'))
}

main().catch((error) => {
  console.error(error)
  process.exitCode = 1
})

A TypeScript migration of markdown-it with modular architecture for tree-shaking and separate parse/render imports.

Compatibility Contract

markdown-it-ts targets the markdown-it public API for common parser, renderer, and plugin usage. Private markdown-it/lib/... imports, undocumented upstream internal state assumptions, direct CommonJS require('markdown-it-ts'), and Node.js < 18 are unsupported.

Level	API surface
Stable target	MarkdownIt(), parse, render, renderInline, renderAsync, renderer.rules, Token, and public ruler/plugin APIs
Advanced	Root withRenderer, documented subpath exports such as core, renderer helpers, and common utilities
Experimental	stream, chunkedParse, StreamBuffer, UnboundedBuffer, EditableBuffer, PieceTable, iterable/sink parsing, and chunk strategy recommenders via markdown-it-ts/experimental; selected helpers also have explicit subpaths such as markdown-it-ts/stream/buffer, markdown-it-ts/stream/chunked, markdown-it-ts/stream/debounced, and markdown-it-ts/support/chunk_recommend

The root entry no longer exposes experimental helpers as top-level named exports. Some large-input helpers remain available as experimental instance methods for compatibility, but they are not part of the stable markdown-it compatibility contract.

Common 0.x import migrations:

0.x import	1.0 import
import { StreamBuffer } from 'markdown-it-ts'	import { StreamBuffer } from 'markdown-it-ts/experimental' or markdown-it-ts/stream/buffer
import { chunkedParse } from 'markdown-it-ts'	import { chunkedParse } from 'markdown-it-ts/experimental' or markdown-it-ts/stream/chunked
import { recommendFullChunkStrategy } from 'markdown-it-ts'	import { recommendFullChunkStrategy } from 'markdown-it-ts/support/chunk_recommend'
import { UnboundedBuffer } from 'markdown-it-ts'	import { UnboundedBuffer } from 'markdown-it-ts/experimental'

Migration Status: CI-backed compatibility baseline

The core TypeScript port is complete. Compatibility is maintained against the markdown-it public API and common plugin patterns with the following goals:

• ✅ Full TypeScript type safety
• ✅ Modular architecture (separate parse/render imports)
• ✅ Tree-shaking support
• ✅ Ruler-based rule system
• ✅ markdown-it public API compatibility for common plugin patterns, backed by the always-on CommonMark fixture test and the plugin compatibility matrix in CI

What's Implemented

✅ Core System

• All 7 core rules (normalize, block, inline, linkify, replacements, smartquotes, text_join)
• CoreRuler with enable/disable/getRules support
• Full parsing pipeline

✅ Block System

• All 11 block rules:
  • table (GFM tables)
  • code (indented code blocks)
  • fence (fenced code blocks)
  • blockquote (block quotes)
  • hr (horizontal rules)
  • list (bullet and ordered lists with nesting)
  • reference (link reference definitions)
  • html_block (raw HTML blocks)
  • heading (ATX headings #)
  • lheading (Setext headings ===)
  • paragraph (paragraphs)
• StateBlock with full line tracking (200+ lines)
• BlockRuler implementation (80 lines)
• ParserBlock refactored with Ruler pattern

✅ Inline System

• All 12 inline rules (text, escape, linkify, strikethrough, etc.) with full post-processing coverage
• StateInline with 18 properties, 3 methods
• InlineRuler implementation mirroring markdown-it behavior

✅ Renderer & Infrastructure

• Renderer ported from markdown-it with attribute handling & highlight support
• Type definitions with Token interface and renderer options
• Helper functions (parseLinkLabel, parseLinkDestination, parseLinkTitle)
• Common utilities (html_blocks, html_re, utils)
• markdownit() instances expose render, renderInline, and renderer for plugin compatibility

Installation

npm install markdown-it-ts

Usage

Basic Parsing (Current State)

import markdownIt from 'markdown-it-ts'

const md = markdownIt()
const tokens = md.parse('# Hello World')
console.log(tokens)

Rendering Markdown

Use the built-in renderer for the markdown-it-compatible render API:

import markdownIt from 'markdown-it-ts'

const md = markdownIt()
const html = md.render('# Hello World')
console.log(html)

Security note: markdown-it-ts is not an HTML sanitizer. Raw HTML is escaped by default, but html: true passes raw HTML through, and plugin-authored attributes are treated as trusted output. Sanitize rendered HTML at your application boundary when untrusted authors can provide raw HTML or plugin-controlled attributes.

Large Inputs

For normal usage, keep the original markdown-it-compatible API:

const md = markdownIt()
const tokens = md.parse(hugeMarkdown)
const html = md.render(hugeMarkdown)

Those default parse / render calls may auto-activate an internal large-input path once the document crosses the large-document threshold. For compatibility, that implicit path is used only when no plugin has been installed and the parser rulers have not been modified. Any .use() call, including renderer-only plugins, keeps the plain full parse path unless you explicitly opt into experimental.fullChunkedFallback; stream parsing has the separate experimental.streamChunkedFallback opt-in.

Use the explicit stream-oriented APIs only when your upstream input already arrives as chunks and you do not want to join it into one giant string first:

import MarkdownIt from 'markdown-it-ts'
import { UnboundedBuffer } from 'markdown-it-ts/experimental'

const md = MarkdownIt()

const tokens = md.parseIterable(fileChunks)

const buffer = new UnboundedBuffer(md, { mode: 'stream' })
for await (const chunk of logChunks) {
  buffer.feed(chunk)
  buffer.flushAvailable()
}
const finalTokens = buffer.flushForce()

Large-input tuning options are available under experimental:

const md = MarkdownIt({
  experimental: {
    autoUnbounded: false,
    fullChunkedFallback: true,
  },
})

The older top-level experimental option names are still accepted for 1.x compatibility, but the namespaced form is preferred.

parseIterable / parseAsyncIterable are advanced entry points for explicit Iterable<string> / AsyncIterable<string> inputs. UnboundedBuffer is the advanced append-only path for real chunk streams and only keeps a bounded tail in memory instead of the whole historical source string.

If you also need bounded output memory for explicit chunk-stream inputs, use the sink form instead of retaining a full token array:

md.parseIterableToSink(fileChunks, (tokens, info) => {
  consumeTokenChunk(tokens, info)
})

For arbitrary in-place edits, use EditableBuffer. It stores the source in a piece table and reparses only from an anchor before the affected block instead of flattening and reparsing the whole document every time. Internally, both the full parse and the localized reparse paths now hand a PieceTableSourceView straight to md.core.parseSource(...), so the selected range no longer needs to be materialized as one giant intermediate string first.

Correctness notes for chunked and streaming parsing

Markdown is not always chunk-local. Some constructs depend on document-level state, including reference definitions, footnote definitions, abbreviation definitions, and plugin-defined global state.

chunkedParse() and complete-string unbounded parsing use a correctness-first fallback by default for known global-state constructs. Chunked parsing also falls back to a full parse when a forced chunk boundary is not on a blank-line boundary, because long lists, blockquotes, HTML blocks, and paragraphs are not safe to split arbitrarily.

Iterable/sink parsing is streaming-oriented. It cannot always know future document-level definitions before committing earlier chunks, so documents with reference, footnote, or abbreviation definitions should use full-string parsing or avoid early flushing when exact full-parse parity is required.

The detector is intentionally conservative. It may fall back for definitions that appear inside code fences or raw text, because fallback is correctness-first.

You can explicitly disable only the known global-state fallback:

chunkedParse(md, source, env, {
  fallbackOnGlobalState: false,
})

Unsafe non-blank chunk boundaries still fall back to a full parse because splitting there is not token-stream safe.

Disabling the global-state fallback is a performance-oriented mode and may produce output that differs from a full parse for documents with global state.

Need async renderer rules (for example, asynchronous syntax highlighting)? Use renderAsync which awaits async rule results:

const md = markdownIt()
const html = await md.renderAsync('# Hello World', {
  highlight: async (code, lang) => {
    const highlighted = await someHighlighter(code, lang)
    return highlighted
  },
})

The main package entry already includes render, renderAsync, renderInline, renderer, and the advanced withRenderer helper. markdown-it-ts/plugins/with-renderer is also kept for custom/core-shaped instances; normal markdown-it-ts users do not need to call it.

Documentation

• Docs index (architecture, plugin dev, streaming, perf)
• Stream optimization & chunked parsing
• Performance report and latest run
• Security notes
• Compatibility report

Why render with markdown-it-ts?

• Compared with markdown-it: familiar public API and common plugin hooks, but rewritten in TypeScript with a modular architecture that can be tree-shaken and that ships streaming/chunked strategies. Normal parse / render usage stays unchanged; plugin/custom-rule instances keep full-parse semantics by default, while stock parser instances can use internal large-input optimizations.
• Compared with markdown-exit: both projects target speed, but markdown-it-ts keeps the markdown-it-style public API, offers typed APIs plus async rendering (renderAsync), and exposes tuning knobs for large-input and append-heavy workloads. Benchmark numbers below are split by corpus and comparison semantics; the stock-subset rows are not a promise that every workload is faster.
• Compared with remark: remark’s strength is AST transforms, and many real workflows include additional unified/rehype stages. In this repository’s Markdown → HTML harness, markdown-it-ts produces HTML directly and keeps markdown-it renderer semantics while still supporting async highlighting or token post-processing.
• Compared with micromark: micromark is a CommonMark-oriented reference implementation with different goals and APIs. markdown-it-ts targets markdown-it’s plugin API and renderer semantics; the numbers below compare only the specific parse/render scenarios measured by this repository’s harness.
• Developer experience: Type definitions and tuning helpers ship in the package (docs/stream-optimization.md, markdown-it-ts/experimental, and documented subpaths for recommend*Strategy, StreamBuffer, chunkedParse, etc.), so teams can build adaptive streaming pipelines quickly. The repository’s benchmark scripts (perf:generate, perf:update-readme) keep comparison data up to date in CI, reducing the risk of unnoticed regressions.
• Migration compatibility: markdown-it-ts preserves the ruler system, Token shape, renderer rules, and public plugin hooks used by common plugins. Plugins that depend on private markdown-it file paths, CommonJS-only loading assumptions, or undocumented internal state require validation.
• 1.0 readiness: top-level root named exports are limited to the stable markdown-it compatibility surface, while streaming buffers, chunked fallbacks, and editable-buffer helpers remain available through markdown-it-ts/experimental; selected helpers also have explicit subpath imports. Some advanced instance methods and options remain available for existing large-input integrations and are marked experimental in the type declarations.

Customization

You can customize parser options and enable or disable specific rules:

import markdownIt from 'markdown-it-ts'

const md = markdownIt({
  linkify: true,
  typographer: true,
  html: false,
}).disable('image')

const result = md.render('Some markdown content')
console.log(result)

Demo

Build the demo site into ./demo and open it in your browser.

Note: the demo build uses the current project's published build artifact (the files in dist/). The demo script runs npm run build before bundling, so the demo reflects the current repo source.

This ensures demo/markdown-it.js is produced from the most recent dist/index.js output.

Generating API docs

You can generate API documentation into ./apidoc using the built-in script. The script will attempt to use pnpm dlx or npx if available, otherwise it uses the locally-installed ndoc from node_modules.

# build and generate docs
npm run build
npm run doc

# open generated docs
open apidoc/index.html  # macOS
xdg-open apidoc/index.html  # Linux

Continuous Integration

This repository has separate workflows for code quality and documentation/demo validation.

• .github/workflows/ci.yml runs lint, typecheck, unit tests, build, package smoke tests, and runtime smoke tests for the packed package.
• The main CI also runs a lightweight parser performance threshold check on Node.js 20 to catch obvious parser regressions without relying on a full benchmark matrix for every PR.
• .github/workflows/ci-docs.yml builds API docs and the demo site, and conditionally deploys them when Netlify secrets are configured.
• .github/workflows/perf-regression.yml is a manual benchmark workflow (workflow_dispatch) for comparing full benchmark snapshots between a base ref and a head ref when a change needs deeper parser/render performance validation.

Files to inspect: .github/workflows/ci.yml, .github/workflows/ci-docs.yml, .github/workflows/perf-regression.yml

Deploying to Netlify

You can deploy both the generated API docs (apidoc/) and the demo site (demo/) to Netlify. There are two supported workflows:

1. Manual / CLI deploy (local)

• Create two Netlify sites (one for docs and one for demo), or use two separate site IDs under the same account.
• Install netlify-cli locally or use the helper scripts included in package.json.

Deploy docs locally:

# set environment variables first
export NETLIFY_AUTH_TOKEN=your_token_here
export NETLIFY_SITE_ID_DOCS=your_docs_site_id
pnpm run netlify:deploy:docs

Deploy demo locally:

export NETLIFY_AUTH_TOKEN=your_token_here
export NETLIFY_SITE_ID_DEMO=your_demo_site_id
pnpm run netlify:deploy:demo

2. CI-driven deploy (recommended)

The repo contains two GitHub Actions workflows, one for docs and one for demo. Each workflow will only run if you add the required secrets to the repository:

• NETLIFY_AUTH_TOKEN — a Netlify Personal Access Token with deploy permissions
• NETLIFY_SITE_ID_DOCS — the Site ID for the docs site
• NETLIFY_SITE_ID_DEMO — the Site ID for the demo site

Add these as GitHub Secrets for the repository (Settings → Secrets and variables → Actions). When pushed to main, the workflows will run and deploy to the corresponding Netlify site.

Files to inspect: .github/workflows/deploy-netlify-docs.yml and .github/workflows/deploy-netlify-demo.yml

Automatic CI deploy: when you push to main, the CI workflow will build the project, generate docs, and build the demo. After a successful build the workflow attempts to deploy both apidoc/ and demo/ to Netlify automatically — but only if the corresponding GitHub Actions secrets are set:

• NETLIFY_AUTH_TOKEN — Netlify Personal Access Token
• NETLIFY_SITE_ID_DOCS — Netlify Site ID for the docs site
• NETLIFY_SITE_ID_DEMO — Netlify Site ID for the demo site

If those secrets exist, the CI will publish both sites. If not, the CI will skip publishing and still report build/lint/docs/demo status.

# build demo and open ./demo/index.html (macOS / Linux / Windows supported)
npm run gh-demo

If you only want to build the demo (skip publishing) you can run:

npm run demo

To publish the demo automatically set GH_PAGES_REPO to your target repo (you must have push access):

export GH_PAGES_REPO='git@github.com:youruser/markdown-it.github.io.git'
npm run gh-demo

Subpath exports

For advanced or tree-shaken imports you can target subpaths directly:

import { Token } from 'markdown-it-ts/common/token'
import { withRenderer } from 'markdown-it-ts/plugins/with-renderer'
import Renderer from 'markdown-it-ts/render/renderer'
import { StreamBuffer } from 'markdown-it-ts/stream/buffer'
import { chunkedParse } from 'markdown-it-ts/stream/chunked'
import { DebouncedStreamParser, ThrottledStreamParser } from 'markdown-it-ts/stream/debounced'

Plugin Authoring (Type-Safe)

Plugins are regular functions that receive the markdown-it-ts instance. For full type-safety use the exported MarkdownItPlugin type:

import markdownIt, { type MarkdownItPlugin } from 'markdown-it-ts'

const plugin: MarkdownItPlugin = (md) => {
  md.core.ruler.after('block', 'my_rule', (state) => {
    // custom transform logic
  })
}

const md = markdownIt().use(plugin)

Performance tips

For large documents or append-heavy editing flows, you can enable the stream parser and an optional chunked fallback. See the detailed guide in docs/stream-optimization.md.

Quick start:

import markdownIt from 'markdown-it-ts'

const md = markdownIt({
  stream: true, // enable stream mode
  streamChunkedFallback: true, // use chunked on first large parse or large non-append edits
  // optional tuning
  // By default, chunk size is adaptive to doc size (streamChunkAdaptive: true)
  // You can pin fixed sizes by setting streamChunkAdaptive: false
  streamChunkSizeChars: 10_000,
  streamChunkSizeLines: 200,
  streamChunkFenceAware: true,
})

let src = '# Title\n\nHello'
md.parse(src, {})

// Append-only edits use the fast path
src += '\nworld!'
md.parse(src, {})

Try the quick benchmark (build first):

npm run build
node scripts/quick-benchmark.mjs

More:

• Full performance matrix across modes and sizes: npm run perf:matrix
• Non-stream chunked sweep to tune thresholds: npm run perf:sweep
• Parser family hotspot report: pnpm run perf:families
• Long-text default strategy matrix: pnpm run perf:strategies
• Independent default-strategy perf gate: pnpm run perf:gate
• See detailed findings in docs/perf-report.md.
• See long-text strategy docs in docs/stream-optimization.md and docs/parse-strategy-matrix.md.

Adaptive chunk sizing

• Non-stream full fallback now chooses chunk size automatically by default (fullChunkAdaptive: true), targeting ~8 chunks and clamping sizes into practical ranges.
• Stream chunked fallback also uses adaptive sizing by default (streamChunkAdaptive: true).
• You can restore fixed sizes by setting the respective *Adaptive: false flags or by providing explicit *SizeChars/*SizeLines values.

Programmatic recommendations

If you want to display or persist the suggested chunk settings without enabling auto-tune, you can query them directly:

import markdownIt from 'markdown-it-ts'
import {
  recommendFullChunkStrategy,
  recommendStreamChunkStrategy,
} from 'markdown-it-ts/support/chunk_recommend'

const size = 50_000

const fullRec = recommendFullChunkStrategy(size)
// { strategy: 'plain', fenceAware: true }

const streamRec = recommendStreamChunkStrategy(size)
// { strategy: 'discrete', maxChunkChars: 16_000, maxChunkLines: 250, fenceAware: true }

These mirror the same mappings used internally when autoTuneChunks: true and no explicit sizes are provided.

Performance regression checks

To make sure each change is not slower than the previous run at any tested size/config, we ship a tiny perf harness and a comparator:

• Generate the latest report and snapshot:

  • npm run perf:generate → writes docs/perf-latest.md and docs/perf-latest.json
  • Also archives docs/perf-history/perf-<shortSHA>.json when git is available

• Compare two snapshots (fail on regressions beyond threshold):

  • node scripts/perf-compare.mjs docs/perf-latest.json docs/perf-history/perf-<baselineSHA>.json --threshold=0.10

• Accept the latest run as the new baseline (after manual review):

  • pnpm run perf:accept

• Run the regression check against the most recent baseline (same harness):

  • pnpm run perf:check:latest

• Run the per-token-type render benchmark against markdown-it:

  • pnpm run perf:render-rules
  • Add --include-noise to also show zero-token / sub-signal categories
  • Use pnpm run perf:render-rules:check to fail if any meaningful category regresses beyond the threshold

• Run the parser rule-family hotspot benchmark:

  • pnpm run perf:families
  • Writes docs/perf-family-hotspots.md and docs/perf-family-hotspots.json

• Run the long-text default-strategy benchmark and gate:

  • pnpm run perf:strategies
  • pnpm run perf:strategy:check
  • pnpm run perf:gate
  • Writes docs/perf-large-defaults.* and docs/parse-strategy-matrix.md

• Inspect detailed deltas by size/scenario (sorted by worst):

  • pnpm run perf:diff

See docs/perf-regression.md for details and CI usage.

Upstream Test Suites

CI always runs the vendored upstream CommonMark good.txt fixture via test/compat/commonmark-fixture.test.mjs, plus the local plugin compatibility matrix.

This repo can also run a subset of the original markdown-it tests and pathological cases. Those optional suites are disabled by default because they require:

• A sibling checkout of the upstream markdown-it repo (referenced by relative path in tests)
• Network access for fetching reference scripts

To enable upstream tests locally:

# Ensure directory layout like:
#   ../markdown-it/    # upstream repo with index.mjs and fixtures
#   ./markdown-it-ts/  # this repo

RUN_ORIGINAL=1 pnpm test

Notes

• Pathological tests are heavy and use worker threads and network; enable only when needed.
• CI keeps only these optional sibling/network suites disabled by default.

Alternative: set a custom upstream path without sibling layout

# Point to a local checkout of markdown-it
MARKDOWN_IT_DIR=/absolute/path/to/markdown-it RUN_ORIGINAL=1 pnpm test

Convenience scripts

pnpm run test:original           # same as RUN_ORIGINAL=1 pnpm test
pnpm run test:original:network   # also sets RUN_NETWORK=1

Performance summary

markdown-it-ts is optimized for parser throughput while preserving the markdown-it public API and common plugin model. The benchmark report now separates three different questions: fixed-configuration native API throughput, tuned/best-of scenarios, and equivalent-output comparisons.

The historical size-based numbers below use the repository's synthetic stock-subset: ATX headings, plain single-line paragraphs, flat tight bullet lists, and fenced code. Its repeated paragraph/list content intentionally exercises the stock-fast parser/renderer and last-output caches. Treat these results as a specialized fast-path benchmark, not as a claim about general Markdown.

Fixed-configuration native API results by corpus

The compact table below reports the synthetic stock subset, a feature-mixed synthetic corpus, and repository-owned MIT-licensed documents independently. It uses default MarkdownIt() instances; the feature-mixed and real-world OX rows enable tables and strikethrough to align those features more closely. Parse rows are native API throughput, not equivalent output: markdown-it-ts returns mutable Token[], while @ox-content/napi returns an object containing an mdast JSON string. Render rows compare native behavior and explicitly report whether HTML is identical.

Corpus	Chars	TS parse	OX parse	TS parse path	TS render	OX render	TS render path	HTML equal?
synthetic stock-subset (~100k)	100,126	0.4758ms	0.8012ms	stock-fast	0.2787ms	0.7201ms	stock-fast	no
synthetic feature-mixed (~100k)	100,450	3.6274ms	0.9461ms	general	4.4958ms	0.8181ms	token-renderer	no
docs/architecture.md	6,564	0.1010ms	0.0219ms	general	0.0971ms	0.0156ms	token-renderer	no
docs/development.md	4,756	0.0988ms	0.0211ms	general	0.1176ms	0.0185ms	token-renderer	no
docs/security.md	1,375	0.0250ms	0.0066ms	general	0.0373ms	0.0063ms	token-renderer	no

No aggregate winner is calculated across corpora. See the generated report for every size, per-file real-world results, strategy diagnostics, and the first HTML output difference.

Tuned/best-of stock-subset results

In the latest local stock-subset snapshot, tuned one-shot parsing compares as follows with upstream markdown-it:

• 5,000 chars: 0.0624ms vs 0.1926ms → ~3.1× faster, ~68% less time
• 20,000 chars: 0.0985ms vs 0.5835ms → ~5.9× faster, ~83% less time
• 100,000 chars: 0.6097ms vs 3.1983ms → ~5.2× faster, ~81% less time
• 500,000 chars: 6.8420ms vs 22.54ms → ~3.3× faster, ~70% less time
• 1,000,000 chars: 11.82ms vs 57.13ms → ~4.8× faster, ~79% less time

Tuned stock-subset parser comparison (markdown-it-ts best one-shot vs @ox-content/napi parse only):

This is a best-of S1–S5 result for markdown-it-ts, not a fixed-configuration headline. The @ox-content/napi parse-only API returns an AST JSON string; these rows compare native throughput with different schemas and do not include a follow-up JSON.parse.

• 5,000 chars: 0.0624ms vs 0.0363ms → ~1.7× slower, ~72% more time
• 20,000 chars: 0.0985ms vs 0.1173ms → ~1.2× faster, ~16% less time
• 100,000 chars: 0.6097ms vs 0.7607ms → ~1.2× faster, ~20% less time

If the @ox-content/napi AST JSON string is immediately materialized into JavaScript objects:

• 5,000 chars: 0.0624ms vs 0.1511ms → ~2.4× faster, ~59% less time
• 20,000 chars: 0.0985ms vs 0.5448ms → ~5.5× faster, ~82% less time
• 100,000 chars: 0.6097ms vs 3.0128ms → ~4.9× faster, ~80% less time

Experimental stock-subset AST JSON output (parseStockFastAstJson) compared with @ox-content/napi parse-only:

• 5,000 chars: 0.0209ms vs 0.0315ms → ~1.5× faster, ~34% less time
• 20,000 chars: 0.0689ms vs 0.1332ms → ~1.9× faster, ~48% less time
• 100,000 chars: 0.3324ms vs 0.8149ms → ~2.5× faster, ~59% less time

What the specialized native baseline teaches us:

• Native parse APIs return different schemas and perform different work, so their timings are useful operational data rather than an equivalent-output ranking.
• Materializing OX's JSON string with JSON.parse measures an additional consumer cost, but still does not make its schema equivalent to markdown-it tokens.
• The experimental parseStockFastAstJson section is the separate equivalent-output comparison: it asserts identical mdast JSON before timing.
• Results depend strongly on corpus shape; consult the feature-mixed and real-world rows before choosing an implementation.

Specialized stock-subset native render behavior (markdown-it-ts.render vs @ox-content/napi parse + render):

These rows use the default render APIs rather than S1–S5 best-of. They are not equivalent-output results: the benchmark records an HTML difference (for example, OX adds heading IDs) and must not be generalized to feature-mixed Markdown.

• 5,000 chars: 0.0162ms vs 0.0354ms → ~2.2× faster, ~54% less time
• 20,000 chars: 0.0552ms vs 0.1823ms → ~3.3× faster, ~70% less time
• 100,000 chars: 0.2778ms vs 0.7098ms → ~2.6× faster, ~61% less time

Legacy stock-subset summary (tuned parse + default native render):

Size	markdown-it-ts parse	@ox-content/napi parse	Parse comparison	markdown-it-ts render	@ox-content/napi render	Render comparison
5,000	0.0624ms	0.0363ms	~1.7× slower, ~72% more time	0.0162ms	0.0354ms	~2.2× faster, ~54% less time
20,000	0.0985ms	0.1173ms	~1.2× faster, ~16% less time	0.0552ms	0.1823ms	~3.3× faster, ~70% less time
100,000	0.6097ms	0.7607ms	~1.2× faster, ~20% less time	0.2778ms	0.7098ms	~2.6× faster, ~61% less time

Non-equivalent stock-subset-only parse / render ranking (5k-200k)

This legacy ranking covers only the specialized synthetic stock-subset; it is not a general Markdown ranking. It is generated from the latest docs/perf-latest.json snapshot. Parse ranking uses the fastest tuned markdown-it-ts one-shot scenario for each size. Render ranking uses default MarkdownIt().render() native behavior, and cross-library HTML is not equivalent, so neither table represents one equivalent-work pipeline.

Parse ranking (one-shot parse, ms)

Size	Rank	Library	oneShotMs
5,000	1	@ox-content/napi	0.0363ms
5,000	2	markdown-it-ts	0.0624ms
5,000	3	markdown-it	0.1926ms
5,000	4	markdown-exit	0.2457ms
5,000	5	remark	3.4843ms
20,000	1	markdown-it-ts	0.0985ms
20,000	2	@ox-content/napi	0.1173ms
20,000	3	markdown-it	0.5835ms
20,000	4	markdown-exit	0.7975ms
20,000	5	remark	16.71ms
50,000	1	markdown-it-ts	0.2367ms
50,000	2	@ox-content/napi	0.3447ms
50,000	3	markdown-it	1.4926ms
50,000	4	markdown-exit	1.9929ms
50,000	5	remark	53.58ms
100,000	1	markdown-it-ts	0.6097ms
100,000	2	@ox-content/napi	0.7607ms
100,000	3	markdown-it	3.1983ms
100,000	4	markdown-exit	4.4228ms
100,000	5	remark	127.31ms
200,000	1	markdown-it-ts	1.3321ms
200,000	2	@ox-content/napi	1.5156ms
200,000	3	markdown-it	7.8202ms
200,000	4	markdown-exit	9.7843ms
200,000	5	remark	329.60ms

Render ranking (parse + HTML output, ms)

Size	Rank	Library	renderMs
5,000	1	markdown-it-ts	0.0162ms
5,000	2	@ox-content/napi	0.0354ms
5,000	3	markdown-it	0.1837ms
5,000	4	markdown-exit	0.2369ms
5,000	5	remark + rehype	3.6978ms
20,000	1	markdown-it-ts	0.0552ms
20,000	2	@ox-content/napi	0.1823ms
20,000	3	markdown-it	0.7353ms
20,000	4	markdown-exit	0.9293ms
20,000	5	remark + rehype	18.82ms
50,000	1	markdown-it-ts	0.1376ms
50,000	2	@ox-content/napi	0.3577ms
50,000	3	markdown-it	1.8077ms
50,000	4	markdown-exit	2.3369ms
50,000	5	remark + rehype	63.50ms
100,000	1	markdown-it-ts	0.2778ms
100,000	2	@ox-content/napi	0.7098ms
100,000	3	markdown-it	4.3147ms
100,000	4	markdown-exit	5.0335ms
100,000	5	remark + rehype	139.61ms
200,000	1	markdown-it-ts	0.5467ms
200,000	2	@ox-content/napi	1.5852ms
200,000	3	markdown-it	9.2046ms
200,000	4	markdown-exit	11.52ms
200,000	5	remark + rehype	348.89ms

For append-heavy editor or streaming workloads, enable the stream parser or use StreamBuffer / UnboundedBuffer. These paths are designed to avoid reparsing stable historical text when the input shape is safe for incremental parsing.

Benchmark results are workload-, CPU-, and Node-version-dependent. docs/perf-latest.json records the Node version, platform, CPU, generated time, benchmark version, and commit for each generated snapshot. Reproduce locally with:

pnpm run build
pnpm run perf:generate

Full parse/render comparisons against @ox-content/napi, remark, micromark, and markdown-exit live in docs/perf-latest.md and docs/perf-report.md. Keep README numbers as a short orientation only; benchmark claims should cite the synthetic harness, environment, and snapshot file.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.

Acknowledgements

markdown-it-ts is a TypeScript re-implementation that stands on the shoulders of markdown-it. We are deeply grateful to the original project and its maintainers and contributors (notably Vitaly Puzrin and the markdown-it community). Many ideas, algorithms, renderer behaviors, specs, and fixtures originate from markdown-it; this project would not exist without that work.

License

This project is licensed under the MIT License. See the LICENSE file for more details.