A Safer Editorial Workflow with Markdown and Diff

Keep one source of truth

Treat Markdown as the content source and rendered HTML as derived output. Editing both independently creates drift. Fix heading hierarchy, list indentation, code fences, and link targets in the source first.

Cleaning copied text can remove invisible spaces and inconsistent line endings, but review code samples where whitespace is meaningful.

Make preview more than a visual check

Live preview exposes skipped headings, overflowing code blocks, and broken nested lists. Test narrow screens too, especially long URLs, wide tables, and unbroken code.

Raw HTML and dangerous URL schemes need sanitization in the publishing pipeline. If the target CMS uses another renderer, verify the final environment as well.

• Use a single H1.
• Do not skip heading levels.
• Write descriptive link text.
• Test code and tables at mobile width.

Review diffs for meaning

Line diffs show broad movement; word diffs expose small semantic changes. Review scope at line level and critical sentences at word level. Pay special attention to negation, numbers, dates, scope, and warranty language.

Whitespace normalization can separate formatting noise from content changes, but compare the original source before approval because Markdown indentation can carry meaning.

Create a measurable publication gate

A practical gate checks links, headings, readability, personal data, claim sources, and the final diff. A readability score is a signal, not a quality verdict; interpret it for the audience and explain unavoidable technical terms.

Keep the approved source and a change summary. This preserves decision context, supports rollback, and helps the next editor understand why the wording changed.