Lossless Markdown editing: the round-trip test suite

A Markdown round trip is one operation: open a file in an editor, save it, compare. It is lossless when the two files are the same bytes. Most rich Markdown editors are not tested against that, so the damage is found by a code reviewer in a diff nobody asked for.

This page is the evidence behind the round-trip claim in @react-markdown-kit/editor: what goes wrong elsewhere, what the suite asserts, and how to run the same suite against your own documents.

What breaks, and why​

The corpus comes from an audit of a production editor, written up in docs/AUDIT.md. The audited editor is not named here as a warning about one package, because the cause is a design that many editors share: it had no Markdown parser. Import and export ran through a transformer protocol that matches Markdown line by line with regular expressions.

Everything below follows from that single choice.

Seven of those were reproducible corruptions that stuck, and compounded on the next save. This is the table from the audit.

Each one is now a fixture. The corpus grew to 22 documents, listed in fixtures/editor-roundtrip/corruption.json, where every case carries the source and a note saying what used to happen to it.

Two layers, two different promises​

Conflating these is how the original bugs went unnoticed, so the suite keeps them apart.

The editor layer is open, look around, close. Byte identity is required. The editor retains the original source and the byte span of every top-level block, and writes unchanged blocks back from those bytes rather than re-serializing them.

The serializer layer is documentToMarkdown(compileMarkdown(source)). That path canonicalizes on purpose, so byte identity is neither expected nor wanted. What must hold there is that the meaning is unchanged, and that saving twice equals saving once. Idempotence is the property the audit was really about, because the damage it found compounded on every save.

Both suites fail the build if a case stops passing. The serializer test also prints the per-case table and holds a list of the cases that are byte-identical today; that list may grow and must not shrink, so losing byte identity is a failure even when the meaning survives.

The 22 documents​

Every case is a real construct, not a synthetic string.

The rows in that table are read from the fixture at build time, so the page cannot drift from the suite.

See it​

Edit one block below. The others come back exactly as they were written: the setext heading stays setext, the tilde fence stays tilde, the loose list keeps its blank lines.

For a document of your own, the editor demo has a panel that does the whole round trip and diffs it line by line. Paste Markdown, save it, read the diff.

Run it against your own documents​

The round trip needs no browser. createMarkdownBridge with headless: true is the same pipeline the React editor runs, built on @lexical/headless, so it works in plain Node.

npm install @react-markdown-kit/editor @react-markdown-kit/renderer

// roundtrip.mjs: node roundtrip.mjs docs/**/*.md
import { readFileSync } from 'node:fs'
import { createMarkdownBridge } from '@react-markdown-kit/editor'
import { defineMarkdownPreset, gfm } from '@react-markdown-kit/renderer'

const preset = defineMarkdownPreset({ extensions: [gfm()] })

let changed = 0
for (const file of process.argv.slice(2)) {
  const source = readFileSync(file, 'utf8')
  const bridge = createMarkdownBridge({ preset, headless: true })
  bridge.load(source)
  const saved = bridge.getMarkdown()
  if (saved !== source) {
    changed += 1
    console.log(`${file}: ${source.length} bytes in, ${saved.length} bytes out`)
  }
}
console.log(`${process.argv.length - 2 - changed} unchanged, ${changed} changed`)

Use the same preset your application renders with. A file that comes back changed is worth reading closely: either it uses a construct your preset does not enable, or it is a bug worth reporting.

As a test, the shape is three lines:

import { describe, expect, it } from 'vitest'
import { createMarkdownBridge } from '@react-markdown-kit/editor'
import { defineMarkdownPreset, gfm } from '@react-markdown-kit/renderer'

const preset = defineMarkdownPreset({ extensions: [gfm()] })

const roundTrip = (source: string): string => {
  const bridge = createMarkdownBridge({ preset, headless: true })
  bridge.load(source)
  return bridge.getMarkdown()
}

describe('our content', () => {
  for (const file of files) {
    it(`${file} survives a save`, () => {
      const source = readFileSync(file, 'utf8')
      expect(roundTrip(source)).toBe(source)
    })
  }
})

The corpus itself is plain JSON with a cases array of { name, source, why }. Nothing in it is specific to this package, so it also runs against any other editor that can import and export a Markdown string.

What is still normalized​

Editing a block rewrites that block, in the serializer canonical form: - bullets, ** for strong, backtick fences, ATX headings. A block you did not edit is not touched, so a commit diff shows what you changed and nothing else.

If you want the canonical form for a whole document on purpose, that is the serializer path: documentToMarkdown(compileMarkdown(source)). Compiling

FAQ​

Next​

Editor demo with the diff panel · @react-markdown-kit/editor on npm · The audit · Source on GitHub

React Markdown editor · Round-trip reference · Compared with MDXEditor · Compared with Milkdown