The Markdown Pre-Publish Checklist

Markdown is readable before it is rendered, which makes small syntax mistakes easy to overlook. A missing blank line can absorb a list, an unmatched fence can turn the rest of a page into code, and a relative link can work in one preview but fail after publication. A pre-publish pass should inspect both the source and the rendered result.

Paste the final draft into the utilkit Markdown Preview and select a preview mode close to the destination. Markdown has shared conventions, but platforms add extensions and differ at edge cases. The CommonMark specification defines a consistent baseline; your actual renderer remains the behavior to verify.

Check the document structure

Use one top-level title when the platform does not supply it, then descend heading levels without skipping merely for visual size. Headings should describe the section for readers and assistive technology. Preview the generated table of contents or anchor links if the destination creates them, because punctuation and duplicate headings can alter IDs.

Put blank lines around lists, block quotes, and fenced code blocks. Confirm nested list indentation in the actual renderer. Keep list items grammatically parallel and avoid using a long list when short paragraphs would make the relationships clearer.

Test every link and image

Open links rather than checking only that they look like URLs. Confirm relative links from the published file’s location, including capitalization on case-sensitive systems. Images need meaningful alternative text when they convey information; decorative images should follow the destination’s accessibility convention.

Do not embed access tokens, private issue links, internal hostnames, or local file paths in content intended to be public. Reference-style links can make a long document easier to edit, but remove unused definitions and verify that every label resolves.

Review code as code

Add a language identifier to fenced blocks when syntax highlighting helps. Copy commands from the preview and run safe examples in a clean environment. Check that placeholders are clearly marked and that shell prompts are not accidentally included in copyable commands.

Escape backticks inside inline code correctly and make sure a code fence is longer than any fence contained in the example. For GitHub content, consult its formatting syntax guide for supported tables, task lists, alerts, and other extensions instead of assuming they travel to another renderer.

Run the final pass

• Preview at desktop and narrow widths.
• Confirm heading order and anchor behavior.
• Open all links and inspect every image.
• Check lists, tables, block quotes, and code fences.
• Search for TODOs, private values, and local-only references.
• Read the rendered version once for meaning, not syntax.

Test instructions in a clean environment

A document can render perfectly and still fail the reader. If it contains setup or recovery instructions, test them from a clean checkout, new account, empty directory, or other realistic starting state. Do not rely on packages, environment variables, permissions, or files left over from the author’s machine. Record the platform and version used so a later reader can tell whether the instructions still apply.

Run every command that is safe to run and verify the stated outcome after each major step. Check filenames, capitalization, relative paths, and code-block languages. For destructive commands, use a harmless fixture or explain the effect precisely. If a sequence branches by operating system or tool version, make the branch visible before the reader reaches an incompatible command.

Finish with a link check and a scan in the actual publishing surface. Relative links may work in a repository preview but fail under a documentation subpath; heading anchors can change with punctuation; and diagrams may become unreadable in dark mode or on a narrow screen. Add a review date only when the instructions were meaningfully rechecked. A reproducible walkthrough is original value that formatting alone cannot provide.

Assign a named owner and a maintenance trigger to procedural documents. A dependency release, renamed command, changed interface, or support incident should create a review task for the pages it affects. Make feedback easy by linking to the source or issue tracker, and remove obsolete alternatives instead of accumulating contradictory notes. Useful documentation is not only complete on publication day; readers can identify its scope, report a defect, and see enough ownership to trust that corrections have somewhere to go.

When a document supports a product release, add it to the release definition of done. Confirm the new behavior, rollback path, configuration, examples, and screenshots against the release candidate, and make documentation failure capable of blocking release when readers would otherwise be harmed. This is especially important for authentication, billing, data migration, and destructive operations. Treating the page as part of the interface produces more value than a final copyedit after implementation decisions are already fixed.

A linter can catch style and syntax problems, but it cannot tell whether a prerequisite is missing or an example is misleading. Combine automation with one human read in the final context. Markdown’s simplicity is an advantage precisely because that last review can focus on the content rather than fighting the format.