Markdown formatting is not just paragraph wrapping. Whitespace can change whether text is a list continuation, a code block, or a new paragraph. The safest formatter tests both source stability and rendered structure.
Choose and name a dialect
CommonMark provides a precise baseline for block and inline parsing. Products may add tables, task lists, footnotes, or raw HTML rules through another flavor. A tool should state the dialect it targets because the same source can render differently across engines.
Build a fixture around ambiguous boundaries
A useful regression document includes:
- ATX and Setext headings.
- Tight and loose lists with nested content.
- Block quotes containing lists or code.
- Fenced code whose content includes backticks.
- Link reference definitions and inline links.
- Escaped punctuation and character references.
- Raw HTML, if the dialect allows it.
This fragment tests a list continuation and a fenced code block:
1. Parse the input.
```json
{"ready": true}
- Compare the rendered tree.
Changing the indentation can move the code block outside the list. A formatter should not make that semantic change merely to align text.
Compare parsed output, not screenshots alone
Rendering before and after is essential, but a screenshot can miss link destinations, heading levels, list start numbers, and code language metadata. Compare a normalized HTML or syntax tree while ignoring only attributes known to be nondeterministic.
Round-trip stability is another useful property: formatting an already formatted document twice should produce the same source on the second run.
Treat raw HTML as untrusted
CommonMark permits raw HTML blocks and inline HTML, but a public preview does not need to execute them. If raw HTML is supported, sanitize it with an actively maintained sanitizer and keep the preview isolated. OWASP notes that encoding and sanitization solve different problems: encoding displays markup as text, while sanitization permits a controlled subset to render.
Do not allow javascript: links, event-handler attributes, or unsandboxed embedded content through a Markdown preview. A Content Security Policy is a secondary control, not the primary sanitizer.
Regression acceptance criteria
- Formatting is idempotent.
- The parsed block and inline structure is unchanged.
- Code-fence content and info strings are preserved.
- Link destinations and reference resolution are unchanged.
- Unsafe HTML and URL protocols stay blocked.
- Large and deeply nested documents terminate within documented limits.