samemark

The same mdast as remark-parse, much faster.

Live demo: a long chat answer streamed into react-markdown (left) and into samemark/stream (right), with per-update timings measured in your browser and a check that both DOMs are identical, plus a playground that compares samemark's tree with mdast-util-from-markdown as you type.

The capture above is the live demo, recorded in headless Chromium on a GitHub Actions runner (capture run 38066505899: 250 updates, 1.76 s of update time on the left, 94 ms on the right, identical HTML at all 25 checks). On your own device the numbers will differ; they are measured in your browser.

samemark is a markdown parser that returns the same mdast tree as mdast-util-from-markdown with GFM (what remark-parse + remark-gfm produce), positions included, and falls back to that real parser for anything it does not reproduce exactly.

micromark by Titus Wormer defines the behavior; this parser matches it and falls back to it. Its test suite and its output are the specification.

How it was made. AI agents wrote most of the code. Every change is checked against micromark's own output: the full tree must be equal, node by node, on thousands of real documents, the CommonMark spec examples, and tens of millions of generated inputs. Nothing here relies on trust in the author or the model; the checks are in this repository and the commands to run them are below.

What you get

In a real unified pipeline (markdown to HTML with remark-gfm, remark-rehype, rehype-stringify) the whole run is 6.2x to 10.3x faster with samemark as the parser, across six inputs on a GitHub Actions runner (Node 24, median of 7 rounds, identical HTML on every file). Parsing alone is 28x to 47x faster; the rest of the pipeline is unchanged, which is why the end-to-end number is smaller.

Streaming a 30,000 character chat answer into a real DOM in Chromium, samemark/stream with memoised blocks spends 60x less main-thread time than react-markdown re-rendering the whole message on every chunk, and 77x less with the CPU throttled 6x as a phone proxy (79.4 s down to 1.03 s over 750 pushes; 103 ms down to 1.1 ms per push), with the same DOM. Swapping only the parser inside react-markdown gives 5x to 6x.

Building a 239-page Astro site took 29.6 s with remark-parse and 22.9 s with samemark (23% less).

All numbers come from one CI run (38036885270) and are reproducible with npm run bench. Details and method: Benchmarks.

• parse(source) returns an mdast Root equal to fromMarkdown(source, {extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()]}).
• remarkParseFast is a drop-in for remark-parse in a unified processor.
• remark-gfm, remark-frontmatter (yaml, toml or both) and remark-math (with or without singleDollarTextMath) are implemented natively, alone or together. Anything else (remark-directive, MDX, custom frontmatter fences, other micromark extensions) is detected and given to the real parser. You get micromark's answer, at micromark's speed.
• No micromark at parse time. The fast path imports six small pure helper packages (four micromark-util-* packages plus ccount and decode-named-character-reference) and nothing else. mdast-util-from-markdown is only needed for the fallback, as an optional peer dependency.

Install

npm install samemark
# for the fallback (recommended; the main entry imports it):
npm install mdast-util-from-markdown unified remark-gfm

Node 18 or newer, or any runtime with ES2020 and TextDecoder (browsers, Deno, Bun, edge runtimes).

Usage

With unified, replace remark-parse:

import {unified} from 'unified'
import remarkGfm from 'remark-gfm'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import remarkParseFast from 'samemark'

const file = await unified()
  .use(remarkParseFast) // instead of remark-parse
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('# Hello *world*')

Inside a framework that already installs remark-parse (Astro, MDX, Next.js plugins), add it to remarkPlugins; it replaces the parser after remark-gfm has registered, which is the order it needs:

// astro.config.mjs
import remarkParseFast from 'samemark'
export default {markdown: {remarkPlugins: [remarkParseFast]}}

With react-markdown (it builds a unified processor on every render with remark-parse first, so a plugin that sets the parser takes over; verified by the benchmark below):

import Markdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import remarkParseFast from 'samemark'

const plugins = [remarkParseFast, remarkGfm] // define once, outside the component

export const Answer = ({text}) => <Markdown remarkPlugins={plugins}>{text}</Markdown>

Chat apps re-render the whole message on every streamed token, so the parser runs again over a growing string each time; see the react-markdown numbers in Benchmarks.

Without a processor:

import {parse} from 'samemark'
const tree = parse('# Hello *world*') // mdast Root

Entries

The main entry also runs a one-time check per processor: three small documents are parsed by both parsers with the processor's own extensions; any difference sends that processor to the fallback (reason: "self-check ... failed"). That guards against a micromark release that changes behavior. It is a tripwire, not a proof.

Options

Both parse(source, options) and remarkParseFast(options) take:

parse additionally accepts extensions and mdastExtensions (the arrays you would give fromMarkdown). Left out, stock GFM is assumed. source may be a string, a Uint8Array (UTF-8) or an object with toString().

Nobody should find out about a fallback in a profiler. stats is exported by both entries:

import {stats, check} from 'samemark'
stats // {fast: 120, fallback: 0, lastFallbackReason: null}
check(micromarkExtensions, fromMarkdownExtensions) // null when the fast path is exact, else the reason

Streaming for chat UIs

Chat UIs re-parse the whole message every time a token arrives. With samemark as the parser that re-parse is 3x to 7x cheaper depending on the runtime, with identical output (react-markdown numbers in Benchmarks). samemark/stream removes the re-parse: it is incremental, and it stays exactly identical to parsing the whole text.

import {createStreamParser} from 'samemark/stream'

const stream = createStreamParser()          // options: {frontmatter, math}, same meaning as remark-frontmatter / remark-math
for await (const chunk of tokens) {
  const tree = stream.push(chunk)            // mdast Root, equal to parse(everything pushed so far), positions included
  render(tree)
}
stream.end()                                 // final tree; stream.reset() starts a new message

• After every push the tree equals what parse() returns for all text so far, which equals micromark's tree. Chunks can split anything: a token, a fence, a table row, a link.
• Blocks that can no longer change keep their object identity from push to push (an unfinished tail is re-parsed, the rest is reused), so React.memo keyed on the node skips them. The cost of a push is the new text plus the unfinished tail, not the whole message.
• A later reference or footnote definition can change how an earlier block resolves; the affected blocks are rebuilt as new objects, so identity changes exactly when the content can have changed.
• Supports stock GFM, optionally with frontmatter and math. For other extensions parse the whole message with the main entry. Also require('samemark/stream') from CommonJS.

A React integration lives in examples/react-chat/StreamMarkdown.jsx: a useMarkdownStream() hook and a <StreamMarkdown tree> component that renders the mdast with mdast-util-to-hast and hast-util-to-jsx-runtime, one memoised block per top-level node, applying the same URL sanitising and raw HTML handling as react-markdown. Its HTML equals react-markdown's for the whole message (test/stream.test.mjs, and the DOM comparison in the Chromium benchmark below).

import {StreamMarkdown, useMarkdownStream} from './StreamMarkdown.jsx'

function Answer({tokens}) {                  // tokens: an async iterable of strings
  const {tree, push, reset} = useMarkdownStream()
  useEffect(() => {
    reset()
    ;(async () => { for await (const chunk of tokens) push(chunk) })()
  }, [tokens])
  return <StreamMarkdown tree={tree} />
}

Streaming cost

Parser only, from node bench/stream-bench.mjs in CI (ubuntu-latest, 12 characters per push, a generated LLM-style answer): total time to push the whole answer, a full re-parse per push against createStreamParser.

Identity of that parser, in CI: 48,196,453 pushes over 465,378 documents (corpus replays, fuzz strings, 1-character, random, token-like and whole-line chunkings, with and without frontmatter and math), each tree compared with a full parse; 0 failing.

React render included (DOM commit, memoised blocks):

From CI run 38036885270 (Chromium, GitHub Actions runner); reproduce locally with npm run bench:stream (jsdom, smaller numbers) or run the bench workflow.

One chat message streamed 40 characters per push into a real DOM node (Chromium 156.0.8078.4, React 19 production, flushSync per push, so each push is parse + React render + DOM commit; layout and paint are not included). (a) react-markdown re-rendering the whole message per push, (b) the same with samemark as the parser, (c) the stream parser with per-block memoisation (examples/react-chat). "Total" is the sum of all push times on the main thread. The DOM after the final push, and after every 25th push, is compared with (a): the last column.

Environment: Node v24.21.0, GitHub Actions ubuntu24 X64 (github-hosted), INTEL(R) XEON(R) PLATINUM 8573C x4, linux x64. Each cell is the median of 7 rounds after one warm-up round, one fresh process per cell.

(a) is what a chat UI does today: react-markdown re-parses and re-renders the whole message on every push. (b) swaps the parser only. (c) is examples/react-chat.

Examples

Each snippet was run against this repository; the unified, frontmatter and fallback ones print what is shown.

unified pipeline (markdown to HTML):

import {unified} from 'unified'
import remarkGfm from 'remark-gfm'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import remarkParseFast from 'samemark'

const file = await unified()
  .use(remarkParseFast)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('# Hello *world*\n\n| a | b |\n|---|---|\n| ~~x~~ | y |')
console.log(String(file))
// <h1>Hello <em>world</em></h1>
// <table> ... <td><del>x</del></td> ... </table>

react-markdown, one line changed:

import Markdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import remarkParseFast from 'samemark'

const plugins = [remarkParseFast, remarkGfm] // module level: not recreated per render
export const Answer = ({text}) => <Markdown remarkPlugins={plugins}>{text}</Markdown>

Streaming chat with samemark/stream. In React use examples/react-chat (the live demo runs it). Without a framework:

import {createStreamParser} from 'samemark/stream'

const stream = createStreamParser()
let tree
for (const chunk of ['# Hel', 'lo\n\nSome **bo', 'ld** text\n\n- a\n- b\n']) {
  tree = stream.push(chunk) // same tree as parse(everything so far); finished blocks keep their identity
}
console.log(tree.children.map(node => node.type)) // [ 'heading', 'paragraph', 'list' ]

Astro:

// astro.config.mjs
import remarkParseFast from 'samemark'
export default {markdown: {remarkPlugins: [remarkParseFast]}}

Frontmatter and math stay on the fast path:

import remarkFrontmatter from 'remark-frontmatter'
import remarkMath from 'remark-math'
import {stats} from 'samemark'

const file = await unified()
  .use(remarkParseFast)
  .use(remarkGfm)
  .use(remarkFrontmatter)
  .use(remarkMath)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('---\ntitle: Notes\n---\n\nEuler: $e^{i\\pi}+1=0$\n')
console.log(String(file)) // <p>Euler: <code class="language-math math-inline">e^{i\pi}+1=0</code></p>
console.log(stats)        // { fast: 1, fallback: 0, lastFallbackReason: null }

samemark parses math into the same inlineMath and math nodes as remark-math; typesetting is the renderer's job, exactly as with remark-parse. Add rehype-katex (or rehype-mathjax) after remark-rehype to turn them into equations:

import rehypeKatex from 'rehype-katex'

unified().use(remarkParseFast).use(remarkGfm).use(remarkMath).use(remarkRehype).use(rehypeKatex).use(rehypeStringify)

samemark/core in the browser (no fallback import; the browser build is about 20 KB gzipped, see Bundle size). It needs a bundler that honours package exports, such as esbuild or Vite:

import {parse} from 'samemark/core'

const tree = parse('# Hello *world*') // mdast Root, GFM

Checking fallbacks so nobody finds one in a profiler:

import remarkDirective from 'remark-directive'
import remarkParseFast, {stats} from 'samemark'

const reasons = []
await unified()
  .use(remarkParseFast, {onFallback: reason => reasons.push(reason)})
  .use(remarkGfm)
  .use(remarkDirective) // not in the supported set: the real parser takes over
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(':::note\nhi\n:::')
console.log(reasons) // ['micromark extension not in the supported set (GFM, frontmatter, math): ...']
console.log(stats)   // { fast: 0, fallback: 1, lastFallbackReason: '...' }

Pass {strict: true} to throw instead of falling back.

Compatibility

Exact statement. The fast path is verified, and only verified, against these pinned versions (package.json devDependencies, installed by npm ci):

Other versions are not claimed. A newer micromark that changes output is caught by the main entry's self-check (it then uses the fallback), and by npm test in this repository, which fails if the stock GFM construct set changes (node scripts/gen-signature.mjs --check).

What counts as supported is decided by construct names, not by function source, so minified bundles of micromark keep the fast path (tested with an esbuild --minify bundle that includes the frontmatter and math extensions). Settings that hide in closures (singleTilde: false, singleDollarTextMath: false, which fences a frontmatter matter uses, anywhere: true) are read by running the real tokenizers on probe strings; the result is compared with what the stock configuration does. Any unknown construct, any disable entry, a custom or anywhere frontmatter matter, or a missing GFM piece means fallback.

Which setups take the fast path

Generated by node scripts/compat-table.mjs from the same cases npm test asserts (each fast row is also compared with remark-parse on a document that exercises it):

Frameworks. Astro (plain markdown, remark-gfm default): fast. Starlight adds remark-directive for asides, so it falls back and gains nothing. Docusaurus and MDX compile through micromark-extension-mdxjs: fallback. @mdx-js/mdx with format: 'md' and remark-gfm: fast.

How identity is verified

Correctness at a glance (every row compares the full tree, positions included, against mdast-util-from-markdown + GFM; details and commands in the table below):

"Identical" means JSON-equal trees including every position, not "looks the same" (firstDiff in bench/common.mjs; undefined fields are treated as absent).

Third-party text is never committed. The docs corpora are fetched at pinned commits (licences: MIT for Node.js, Vite and React, MIT or Apache-2.0 for the Rust book, BSD-2-Clause code with CC-BY-SA spec text for the GFM spec examples), the README corpus is rebuilt from npm by sha256 manifest, and the synthetic corpus is generated from a seed.

Known differences

On the tested set (spec examples, corpora, held-out, edge inputs) there are none. Differential fuzzing did find shapes that differ, all block-level corners around footnote definitions and lists; they are listed with minimal inputs in KNOWN_GAPS.md and none occurs in a real document so far. What is not covered by the identity claim: non-GFM extensions (they fall back, by design), non-string input types, and pipelines other than the ones in the compatibility table.

Behavior that is different on purpose: micromark throws a RangeError on roughly 10,000 levels of nesting; samemark parses it. Large single inputs: micromark's time grows faster than linearly with document size (a mixed document took 1.6 s at 400 KB, 5.1 s at 800 KB and 19 s at 1.6 MB on a fast laptop; one 500 KB paragraph of inline markup takes 16 s; a 10 MB comparison ran 42 minutes and exhausted a 6 GB heap), while samemark parsed a 10 MB mixed document in about 0.4 s. That is why the full-tree comparison in the edge tests stops at 2 to 3 MB and the 10 MB cases only check that samemark finishes and does not throw.

Benchmarks

Which numbers come from which input. The tables below were produced by the bench workflow (and the parser-level stream benchmark by bench/stream-bench.mjs) while the project lived in a private repository. Rows named "README corpus" ran on the 4,780-file development corpus of npm package READMEs (a 1 in 4 or 1 in 16 sample for the slower tests; 4,648 of the files are rebuildable from bench/readme-corpus-manifest.json). Rows named after a repository (node-api-docs, rust-book, vite-docs, node-changelog-v22, react-changelog) ran on the pinned commits in bench/corpora.json; anyone can fetch exactly those with npm run corpus. The react-markdown tables use the generated chat-style answer (bench/perf/chat-text.mjs), the Astro site uses the three docs sets, and npm run bench on a fresh checkout measures the pinned docs sets plus the synthetic corpus (and the README corpus with --readme once it is rebuilt). Runner CPUs differ between jobs and runs, so compare the ratios within a table, not absolute times across tables.

Environment: Node v24.21.0, GitHub Actions ubuntu24 X64 (github-hosted), AMD EPYC 7763 64-Core Processor x4, linux x64. Each cell is the median of 7 rounds after one warm-up round, one fresh process per cell.

End to end: markdown to HTML with unified

unified().use(parser).use(remarkGfm).use(remarkRehype).use(rehypeStringify), with remark-parse or with samemark as the parser. Output HTML is compared file by file.

Content pipeline, as a docs or blog site runs it: remark-gfm, remark-frontmatter (yaml) and remark-math before remark-rehype. vite-docs has real frontmatter in every page; the synthetic (or README) documents get a generated block so every file has one. Both sides are compared on the HTML.

For context, other converters on the same input (different pipeline and output: HTML strings, no mdast, not drop-in replacements):

Environment: Node v24.21.0, GitHub Actions ubuntu24 X64 (github-hosted), AMD EPYC 7763 64-Core Processor x4, linux x64. Each cell is the median of 7 rounds after one warm-up round, one fresh process per cell.

react-markdown (desktop, Node, renderToStaticMarkup, React production build)

react-markdown 10.1.0 builds a new unified processor on every render (unified().use(remarkParse).use(remarkPlugins)...), so remarkPlugins={[remarkParseFast, remarkGfm]} replaces its parser on every render. The input is a synthetic chat-style answer (headings, lists, code, tables, links; bench/perf/chat-text.mjs). Output HTML is compared at 120 prefix lengths, partial constructs included: 120/120 identical. samemark path: 6148 fast, 0 fallback.

One update at a fixed message length (this is also the cost of rendering a finished long answer):

Streaming simulation: the message grows by a few characters at a time and the whole message is re-rendered after each step, as chat apps do:

react-markdown in Chromium, CPU throttled as a phone proxy

Chromium 156.0.8078.4, react-markdown 10.1.0 production bundle, renderToStaticMarkup in the page. CPU throttling uses DevTools Emulation.setCPUThrottlingRate (4x and 6x slowdown of the main thread). It is a proxy for a slower device, not a measurement of one. Same chat-style input as the desktop table; streaming steps are 100 characters here to keep the throttled runs short.

Streaming a 30,000 character answer into the DOM

One chat message streamed 40 characters per push into a real DOM node (Chromium 156.0.8078.4, React 19 production, flushSync per push, so each push is parse + React render + DOM commit; layout and paint are not included). (a) react-markdown re-rendering the whole message per push, (b) the same with samemark as the parser, (c) the stream parser with per-block memoisation (examples/react-chat). "Total" is the sum of all push times on the main thread. The DOM after the final push, and after every 25th push, is compared with (a): the last column.

Environment: Node v24.21.0, GitHub Actions ubuntu24 X64 (github-hosted), INTEL(R) XEON(R) PLATINUM 8573C x4, linux x64. Each cell is the median of 7 rounds after one warm-up round, one fresh process per cell.

Parse only

Same mdast on both sides (mdast-util-from-markdown with micromark-extension-gfm and mdast-util-gfm, the reference). "Identical" counts files whose full tree, positions included, is equal.

Other parsers on the same input. Different output: markdown-it returns a token list and marked returns its own token tree, neither is mdast, and neither is a drop-in replacement. Shown for scale only.

Environment: Node v24.21.0, GitHub Actions ubuntu24 X64 (github-hosted), AMD EPYC 7763 64-Core Processor x4, linux x64. Each cell is the median of 7 rounds after one warm-up round, one fresh process per cell.

MDX (@mdx-js/mdx compile)

Plain format: 'md' with remark-gfm, default parser versus samemark as the parser. format: 'mdx' loads micromark-extension-mdxjs, which is not in the stock GFM set, so samemark falls back there by design; it is measured on the files that are valid MDX to show the overhead is nil. Compiled output is compared.

Real site: Astro 6.4.8 building 239 real markdown pages

rust-book, vite-docs, node-api-docs (6.53 MB of markdown), stock Astro markdown pipeline (remark-parse, remark-gfm, smartypants, Shiki, rehype-raw). Cold build each time (dist, .astro and the Vite cache removed), 3 builds per variant alternating, median shown, Node v24.21.0, AMD EPYC 7763 64-Core Processor x4.

Build time saved: 6.7 s (22.7%). Parser time saved: 6.57 s.

Individual builds (s): default 29.2, 29.6, 29.7; samemark 22.7, 22.9, 23.3.

Reading the react-markdown numbers. The speedup per update is smaller than the parse-only number because React rendering and the hast to JSX step are unchanged. It differs by runtime: Node 6.5x to 7.0x, unthrottled Chromium 4.8x to 5.4x, throttled Chromium 5.3x to 6.6x. I do not have a verified explanation for why the ratio grows under CPU throttling (throttling slows the main thread; garbage collection and compilation threads are not slowed the same way, which is a guess, not a measurement). The absolute numbers are the practical result: a finished 30,000 character answer renders in 35 ms instead of 200 ms at 6x throttle.

Reproduce:

npm ci
npm run bench:small   # a few seconds: the synthetic corpus sample plus one changelog, laptop sized
npm run bench         # the full run (what CI ran), fetches the pinned documents first

npm run bench prints the exact tables above. Method: each cell is one fresh Node process (own JIT and heap), one warm-up round, then the median of the stated number of rounds over all files of the input; GC is forced between rounds; both sides are compared for identical output before timings are reported (the run fails otherwise). markdown-it and marked are included for scale only: they produce tokens or HTML, not mdast, and are not drop-in replacements. Documents: bench/corpora.json pins repository, commit and sha256 of every set.

Bundle size

Minified with esbuild, ESM, platform neutral. node scripts/size.mjs reproduces the table.

The browser row is what a bundler produces for browsers: decode-named-character-reference then decodes entities through the DOM instead of shipping its 35 KB table. Edge runtimes (workerd, worker, edge-light, deno) get the table.

Where it fits

Sätteri, the Rust engine that is the default markdown processor in Astro 7, says in its docs that it "isn't a drop-in replacement for unified" and that existing remark and rehype plugins won't run unmodified. samemark is for the projects that stay on unified: the same mdast, existing plugins run unchanged, and it is plain JavaScript with no native binary.

Credits

• micromark, mdast-util-from-markdown and the GFM extensions by Titus Wormer and contributors define the behavior this parser reproduces, and supply the helper packages it imports (micromark-util-*, ccount, decode-named-character-reference).
• The CommonMark spec and its examples.
• unified and remark.

License

MIT. Third-party licences of the code bundled in dist/core.cjs are in dist/LICENSES.txt.