A reliable Markdown workflow catches syntax errors, broken links, inconsistent headings, and rendering surprises before documentation reaches readers. This checklist explains how to lint, preview, validate, and review README files, release notes, and longer documentation across repositories, static sites, and package platforms.
Overview
Markdown is easy to write but not always easy to maintain. A document can look correct in an editor while containing a broken relative link, an incorrectly nested heading, an unclosed code fence, or an image with no useful alternative text. It can also render differently when moved between CommonMark-oriented tools, GitHub Flavored Markdown (GFM), a static-site generator, and a package registry.
A practical documentation workflow separates four checks:
- Format: Apply a shared style for headings, lists, spacing, code, and tables.
- Lint: Detect structural and stylistic problems automatically.
- Preview: Inspect the rendered result in the target platform or an equivalent local environment.
- Validate: Check links, images, anchors, code examples, and accessibility before merging.
A Markdown editor preview can help during drafting, but it should not replace a repository check. Preview tools may support extensions that your publishing platform does not, or omit platform-specific behavior such as automatic heading anchors, task lists, tables, alerts, or raw HTML handling.
Checklist by scenario
For a new README or documentation page
- Start with one clear
H1that describes the page. - Use
H2headings for major topics and do not skip heading levels merely to change text size. - Give the reader an early path to the next action, such as installation, a quick start, or an example.
- Use fenced code blocks with a language identifier, for example
```bashor```javascript. - Explain required variables, permissions, operating-system assumptions, and expected output.
- Use descriptive link text rather than phrases such as “click here.”
- Add meaningful alternative text to informative images and use an empty
altvalue for purely decorative images when the platform supports it. - Preview the page using the same renderer, or as close an equivalent as practical, to the final publishing destination.
For an edited README or pull request
- Review the rendered diff, not only the raw source diff.
- Confirm that moved or renamed files do not leave relative links pointing at old paths.
- Check that new headings do not create confusing or duplicate anchor targets.
- Run the project’s Markdown linter and link checker locally or in CI.
- Verify that code samples still match the current commands, API names, configuration keys, and output.
- Look for accidental whitespace changes inside lists, blockquotes, tables, and fenced blocks.
- Ask whether the change needs an update to the table of contents, navigation, changelog, or release notes.
For release notes
- Use a consistent date, version, and heading pattern.
- Separate breaking changes, fixes, improvements, and known limitations where that helps scanning.
- Link issue numbers, pull requests, migration instructions, and affected documentation.
- Remove internal comments, unfinished placeholders, and links to private systems.
- Check that the document renders correctly both in the repository and wherever release notes are syndicated.
For a platform migration
- List every extension currently used, including tables, task lists, footnotes, alerts, diagrams, and embedded HTML.
- Test representative pages rather than assuming identical Markdown behavior.
- Compare heading anchors, image paths, code highlighting, escaping, and HTML sanitization.
- Replace unsupported syntax with portable Markdown or document the platform dependency.
- Run a site-wide link and image audit after paths, navigation, or base URLs change.
Markdown syntax and lint-rule reference
Rule names vary by linter and configuration, but the underlying checks are broadly similar. Treat this table as a review map, then confirm the exact identifiers supported by the tool used in your repository.
| Area | What to check | Why it matters |
|---|---|---|
| Headings | One page title, logical hierarchy, consistent spacing | Improves navigation, scanning, and generated outlines |
| Blank lines | Separate headings, lists, paragraphs, quotes, and code fences | Prevents ambiguous parsing and inconsistent rendering |
| Lists | Consistent markers and indentation; continuation lines aligned | Reduces accidental nesting and difficult-to-read source |
| Code fences | Closing fence present; language identifier included | Preserves examples and enables appropriate highlighting |
| Links | Descriptive text, valid destinations, no empty or duplicate references | Supports usability and prevents dead ends |
| Images | Valid path, useful alternative text, sensible dimensions | Protects accessibility and avoids broken visual content |
| Tables | Matching columns, readable cell content, deliberate alignment | Prevents malformed or inaccessible tabular output |
| Line length | Follow the repository’s agreed limit, if one exists | Keeps source diffs manageable without treating prose as code |
A reusable baseline configuration should be explicit about rules that affect your team. For example, a Markdown linter configuration can enable heading hierarchy checks, require fenced code languages, flag bare URLs, enforce consistent list markers, and allow documented exceptions. Keep exceptions narrow and comment on the reason. A configuration that disables most rules is less useful than a smaller set that contributors understand.
# Example policy outline — adapt rule names to your linter
rules:
heading-style: consistent
heading-increment: enforce
blanks-around-headings: required
blanks-around-fences: required
fenced-code-language: required
list-marker-style: consistent
link-text: descriptive
no-bare-urls: preferred
no-duplicate-heading: error
line-length: 120
The example is a policy outline, not a drop-in configuration for a specific linter. Check the selected tool’s documentation before committing rule names or severity values.
What to double-check before merging
Links and anchors
Check Markdown links in two ways: inspect the source for incorrect relative paths, then run a link checker against the rendered site or repository. A source-level check may miss redirects, generated pages, or anchors that only exist after publishing. Pay special attention to links containing spaces, case-sensitive paths, fragments, and URLs that depend on a site base path.
Do not treat a successful HTTP response as proof that a link is useful. A destination can exist but lead to the wrong section, an authentication page, or an obsolete version. Review important links manually.
Code fences and examples
Confirm every opening fence has a matching closing fence. A missing fence can cause the rest of a page to render as code. Check shell prompts, indentation, placeholders, secrets, operating-system syntax, and copy-paste behavior. Examples should not expose credentials, private hostnames, tokens, or production data.
Tables and images
Tables are useful for compact comparisons, but wide or complex tables can be difficult on small screens and with assistive technology. Consider a list or separate subsections when cells contain long prose. For images, verify the path from the publishing environment, not only from the source file’s location. Describe the information conveyed by a screenshot rather than repeating its filename.
Rendering differences
CommonMark defines core parsing behavior, while GFM and other platforms add extensions. Test features that are not plain Markdown, including task lists, tables, strikethrough, footnotes, alerts, embedded HTML, and automatic URL linking. If documentation is published in more than one place, define which rendering is authoritative and test the most restrictive target.
Common mistakes
- Relying on one preview: An editor preview may not match the repository, static-site generator, or package documentation renderer.
- Linting without validating links: Most style linters do not prove that every destination or image exists.
- Using headings for visual size: Heading levels communicate structure; use CSS or platform styling for presentation.
- Leaving exceptions unexplained: Suppressed rules become permanent blind spots unless the reason and scope are recorded.
- Checking only changed lines: A heading rename or path move can break references elsewhere in the repository.
- Assuming HTML is portable: Raw HTML, scripts, embedded media, and custom attributes may be removed or rendered differently.
- Ignoring accessibility during content review: Missing image descriptions, ambiguous links, and overly complex tables affect real readers even when the page looks correct.
For related validation habits, pair this workflow with an OpenAPI documentation validation workflow when Markdown describes an API, and review the web accessibility testing workflow when documentation is part of a public web experience.
When to revisit
Revisit this checklist before each substantial documentation pull request, release-note pass, or README restructure. Run a broader link and rendering audit after a repository move, domain change, static-site migration, publishing-tool change, or navigation redesign. It is also useful before seasonal planning cycles, when teams often consolidate guides and archive outdated pages.
Review the linter configuration and platform assumptions whenever the Markdown parser, editor integration, link checker, static-site generator, or repository workflow changes. A practical maintenance interval is every four to six months, or sooner when a tool introduces a significant behavior change. Record the last tested renderer and the intended Markdown flavor in the repository’s contributor documentation.
Action checklist: run the formatter or linter, check links and images, preview the rendered page, inspect the complete diff, test representative platform-specific syntax, and ask one reviewer to follow the documented steps as a reader. Fix errors before merge; document intentional exceptions so the next update starts from a known baseline.