Markdown publishing checklist for converted files

Who this guide is for

• • Editors approving converted content for a public site or documentation portal
• • Developers committing generated Markdown to a repository
• • Knowledge-base teams preparing reviewed source material for indexing
• • Owners of policies, runbooks, reports, and reference tables

What should be checked against the source first?

Verify the title, section order, names, dates, versions, totals, units, clauses, warnings, and any other detail that changes meaning. Keep the original file open beside the Markdown. Do not begin by polishing prose if the extraction order or factual values may be wrong.

Does the Markdown have a clear document structure?

Use one primary H1, logical H2 and H3 levels, complete paragraphs, consistent list syntax, and meaningful section boundaries. Remove page numbers, repeated headers, empty bullets, decorative separators, and headings inferred from isolated labels without context.

Are tables, code blocks, links, and images usable?

Rebuild irregular tables, verify numeric alignment and escaping, add language labels to code fences, test every important link in the destination, migrate image assets, and provide alt text or a text explanation. Confirm that code has not acquired smart quotes, wrapped lines, or missing indentation.

What metadata and access decisions are required?

Record a source URL or file reference, owner, version, review date, and access classification when the workflow needs traceability. Remove private comments, credentials, internal hosts, customer identifiers, and unapproved personal data. Ensure the destination permissions match the content classification.

How should the final render be tested?

Preview the Markdown in the actual repository, CMS, documentation engine, or knowledge-base interface. Check desktop and mobile layouts, heading anchors, table scrolling, code wrapping, image sizing, callouts, and any renderer-specific extensions. A Markdown editor preview may not behave like the production renderer.

Before and after example

# Incident Report
Page 2 Confidential
## Root Cause
- Service timeout
Total impacted: 1O2
[Dashboard](http://internal-host/)

# Incident Report

**Source:** Incident review 2026-07
**Owner:** Operations
**Last reviewed:** 2026-07-17

## Root cause

- Service timeout

**Verified impacted users:** 102

Internal dashboard link removed from public copy.

Final publishing checklist

• • Compare the complete Markdown with the original source.
• • Verify title, heading hierarchy, paragraph order, and list nesting.
• • Check names, dates, totals, units, clauses, warnings, and commands.
• • Rebuild or split tables that are irregular or too wide.
• • Test code blocks, links, heading anchors, images, captions, and alt text.
• • Add source, owner, version, and review metadata where required.
• • Remove private comments, credentials, internal paths, customer data, and temporary URLs.
• • Render in the actual destination on desktop and mobile.
• • Keep the source and review record until the publication is approved.

Risk boundary

Publishing converted Markdown transfers responsibility to the reviewer and content owner. Do not use an unverified conversion as the authoritative legal, medical, financial, safety, compliance, or operational record. Sensitive material must remain in an approved private workflow with appropriate access controls and retention rules.