Lossless Markdown editing: the round-trip test suite

A Markdown round trip means opening a file in an editor, saving it, and comparing the two. It's lossless when they're the same bytes. Most rich Markdown editors aren't tested against that, so the damage usually gets noticed by a code reviewer looking at a diff nobody asked for.

This page backs up the round-trip claim in @react-markdown-kit/editor. It covers what goes wrong in other editors, 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, because the problem is a design a lot of editors share. It had no Markdown parser. Import and export ran through a transformer protocol that matches Markdown line by line with regular expressions.

Most of what's in the table below comes from that one decision.

Seven of those were reproducible corruptions that stuck around and got worse with each save. Here's 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.

Editor layer and serializer layer​

Mixing these two up is how the original bugs went unnoticed, so the suite tests them separately.

The editor layer covers opening a document, looking around and closing it. Byte identity is required here. The editor keeps the original source and the byte span of every top-level block, and writes unchanged blocks back from those bytes instead of re-serializing them.

The serializer layer is documentToMarkdown(compileMarkdown(source)). That path canonicalizes on purpose, so we don't expect or want byte identity there. What has to hold is that the meaning doesn't change and that saving twice gives the same result as saving once. Idempotence is what the audit really cared about, since the damage it found got worse on every save.

Both suites fail the build if a case stops passing. The serializer test also prints the per-case table and keeps a list of the cases that are byte-identical today. That list can grow but shouldn't shrink, so losing byte identity counts as a failure even if the meaning survives.

The 22 documents​

Each case is a construct you'd actually find in documents (none of them are made-up strings).

The table rows are read from the fixture at build time, so the page stays in sync with the suite.

See it​

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

If you want to try 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​

You don't need a browser for the round trip. 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. If a file comes back changed, it's worth a close look. Either it uses a construct your preset doesn't enable, or it's a bug worth reporting.

As a Vitest test it looks something like this:

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 }. None of it is specific to this package, so you can run it against any other editor that imports and exports a Markdown string.

What is still normalized​

Editing a block rewrites that block in the serializer's canonical form (- bullets, ** for strong, backtick fences, ATX headings). Blocks you didn't edit are left alone, so a commit diff only shows what you changed.

If you do want the whole document in canonical form, use 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