A Markdown file can be valid plain text and still produce a broken document. A heading may skip a level, a table may have the wrong number of columns, a relative image may point nowhere, or a Mermaid block may fail only when a renderer tries to draw it. A useful Markdown checker therefore needs to do more than recognize punctuation.
This guide provides a render-focused test for README files, technical documentation, and AI-generated Markdown. It is about checking correctness before sharing or printing, not about choosing another Markdown editor.
Markdown quality has three layers:
A linter is excellent at the first layer. A live preview helps with the second. A print or export check catches the third. For a technical document, none of those checks is a complete substitute for the others.
Start with one descriptive H1. Use H2 sections for the main outline and H3 headings only inside those sections. A sequence such as H1, H2, H4 may look acceptable after styling, but it creates a misleading document outline for navigation and assistive technology.
Also check for headings used only as visual labels. If a line does not introduce a section, bold text may be more appropriate than another heading level.
Nested lists depend on consistent indentation. Render them and make sure child items remain beneath the intended parent. This is particularly important in AI-generated plans, where one misplaced space can flatten a decision tree.
Every fenced code block needs an opening and closing fence. Give the block a language when syntax highlighting matters:
```javascript
console.log("checked");
```One unclosed fence can turn the rest of a document into code. Search the raw source for triple backticks, but always confirm the result in a preview because fences can also be nested or use tildes.
A table needs a header, a delimiter row, and compatible column counts. This source is broken because the header has three cells while the delimiter has two:
| Service | Owner | Status |
| --- | --- |
| Renderer | Docs | Ready |Even a structurally valid table can fail as a reading experience. Check long cell content, code inside cells, and tables wider than the viewport. If the document contains a large matrix, test horizontal scrolling and the printed result instead of checking only that pipes became borders.
Review each link type separately:
Anchor rules vary between renderers, especially when headings contain punctuation or repeated words. Relative paths vary with the document's final location. A link that works beside the source repository may break after the Markdown is uploaded or shared alone.
The Markdown link syntax guide contains examples for URLs, repository files, images, and anchors. For moved assets, see how local Markdown files handle images and relative links.
Do not count a Mermaid fence as valid merely because it has an opening and closing line. A parser must render the contents.
For each diagram, verify that:
If one block fails, isolate it before changing the surrounding document. Mermaid Studio can test a single block, while the broken Mermaid guide explains common repair steps.
Math delimiters are not implemented identically everywhere. Confirm both inline formulas and display equations in the target renderer. Do the same for callouts, footnotes, task lists, and any extension-specific syntax.
A checker should report unsupported content rather than silently presenting it as ordinary text. Raw $ delimiters or a Mermaid source block may preserve the data, but they do not deliver the intended document.
For a README, test the document from the perspective of a first-time visitor:
The complete README preview checklist covers GitHub-specific review without mixing it into the general Markdown check.
Printing introduces failures that do not appear on screen. Look for clipped tables, diagrams split across pages, code lines cut off at the margin, nearly blank pages, and headings stranded at the bottom of a page.
Use the Markdown printing and PDF guide for a dedicated export checklist. A render that looks correct in a wide browser window is not automatically print-ready.
Manual review is appropriate for a one-off file. Generated documentation and frequently updated architecture files need a repeatable gate. The workflow should update the same document, run a production render check, fail when a diagram cannot render, and export only after verification succeeds.
The CLI render-verification guide shows how to add that process to an agent or CI job. Automation is especially valuable for AI-generated Markdown because structural errors can reappear on every generation.
The central rule is simple: inspect the source, render the document, and test the output people will actually receive. A Markdown checker is most trustworthy when it verifies all three.