Practical guide
Markdown cleanup checklist after conversion
A successful file conversion produces a draft, not a finished document. Review heading hierarchy, paragraph order, list nesting, tables, links, images, code fences, repeated boilerplate, metadata, and source-critical details before publishing. Keep the original file beside the Markdown until names, dates, totals, clauses, identifiers, and other high-risk values have been verified.
Last reviewed July 17, 2026 · Release 2026-07-17-adsense-r9
Who this guide is for
- • Editors and documentation teams
- • Developers reviewing generated Markdown
- • Content migration projects
- • RAG and knowledge-base preparation teams
Are headings structural rather than decorative?
Use one H1 for the document title, H2 for major sections, and H3 only where a real subsection exists. Demote short labels that were promoted from visual styling alone.
Do paragraphs appear in the correct reading order?
Join hard-wrapped lines, split unrelated blocks, remove repeated page furniture, and compare column or slide order with the source.
Are lists nested and numbered correctly?
Check indentation, restarted numbering, empty bullets, task markers, and paragraphs that were mistaken for list items.
Are tables readable and trustworthy?
Verify headers, rows, totals, units, dates, currencies, negative values, and merged-cell meaning. Split wide tables or replace them with record lists.
Do links, images, and code still work?
Repair relative URLs, add useful link labels, confirm image paths and alt text, and place code or logs inside fenced blocks with the right language label.
Is the document ready for its destination?
Add title, source metadata, owner, version, last reviewed date, access classification, and any front matter required by the CMS, repository, or knowledge base.
Before and after example
Before
# Report ### Overview • • First item Page 2 | Total | 1,24O | relative/link
After Markdown
# Report ## Overview - First item | Item | Total | |---|---:| | Verified total | 1,240 | [Related source](https://example.com/source)
Review checklist
- • One H1 and a logical H2/H3 hierarchy.
- • Correct paragraph and section order.
- • No empty bullets or broken numbering.
- • Tables verified against the source.
- • Links, images, and code fences tested.
- • Page headers, footers, and duplicate boilerplate removed.
- • Names, dates, totals, clauses, and IDs checked.
- • Metadata and access guidance added for the destination.
Risk boundary
Converted Markdown remains a draft. Use an approved private workflow for confidential, regulated, customer, financial, medical, legal, credential-containing, or private source material. Keep the original source available until all material details are verified.
Frequently asked questions
Should I remove every page number and header?
Remove repeated page furniture unless it provides meaningful references or legal context.
How wide can a Markdown table be?
There is no strict limit, but readability drops quickly. Split or summarize wide tables.
Should converted HTML be allowed inside Markdown?
Only when the destination supports and sanitizes it. Prefer plain Markdown for portability.
How do I check list nesting?
Render the Markdown and compare indentation and numbering with the source outline.
What should be verified first?
High-risk facts: names, dates, amounts, totals, clauses, units, identifiers, and links.
When can the source file be archived?
After the Markdown is reviewed and the retention or record policy for the source is satisfied.
Related workflows
These links provide the next format, privacy, or review step for this specific guide.