What makes a good markdown WYSIWYG editor

Rendering markdown as you type is the easy part. Handing back a file that still looks like the one you opened is where most editors fall down.

A WYSIWYG markdown editor shows formatted text while you write instead of raw syntax. You see a real heading rather than ## Heading, a real bulleted list rather than a column of hyphens. The appeal is obvious: markdown's syntax is small, but reading it while also reading your own prose is a tax you pay on every sentence.

The catch is that markdown is a file format, not a document model. Every WYSIWYG editor has to parse your text into an internal tree, let you edit that tree, and then write markdown back out. That last step is where the trouble lives.

Round-trip fidelity is the whole game

Round-trip fidelity means: open a file, change nothing, save it, and get back byte-identical text. It sounds like a low bar. Most editors miss it.

The usual failure is that the serializer has opinions. You open a file that uses:

* Item one
* Item two

and the editor saves it back as:

- Item one
- Item two

Nothing is broken. The rendered output is identical. But if that file is in version control, your diff now shows every list in the document as changed, and the one real edit you made is buried among a hundred cosmetic ones. Reviewers stop reading. On a shared repository this is enough to get a tool banned outright.

The same class of problem shows up in a dozen places:

Why the problem is genuinely hard

Markdown has no single specification. CommonMark standardised the core, but the flavours people actually use — GitHub Flavored Markdown, tables, footnotes, task lists, callouts, frontmatter, math — are extensions layered on top, and they interact. A tight list and a loose list differ only by a blank line, and that blank line changes the generated HTML. Nested list indentation can be two spaces or four, and both are valid.

So a serializer faces a choice on every node: preserve what the author wrote, or normalise to one house style. Preserving is much harder, because it means the editor has to carry the original formatting alongside the parsed structure and use it wherever the content was not actually edited. Normalising is easy, and it is why so many editors do it.

Three ways to edit, and when each one helps

No single view is right for everything, which is why serious markdown editors offer more than one:

• Rich mode — full WYSIWYG. Best for drafting prose, where syntax is pure friction and you want to think about sentences.
• Raw mode — plain markdown source with syntax highlighting. Best when you need exact control: fixing a table's alignment, checking what a serializer actually emitted, or editing frontmatter.
• Dual mode — source and rendered output side by side, kept in sync. Best for learning the syntax, and for documents where structure matters more than flow, like technical references.

The important detail is that switching modes should never itself change the file. If moving from rich to raw and back reformats your document, the modes are not really views of the same thing.

A short checklist

Before committing to any markdown WYSIWYG editor, check that it:

• survives the git diff test above
• preserves your line endings rather than normalising to one kind
• leaves frontmatter alone instead of reordering or reformatting keys
• lets you drop into raw source when you need it
• renders the extensions you actually use — tables, task lists, math, diagrams
• stores files where you can reach them without exporting

MarkNow is built around the first item on that list. It offers rich, raw, and dual modes over the same document, and the serializer is written to leave untouched text untouched. You can open it in the browser with no signup and try the diff test on your own files in under a minute.