Markdown SOP publishing checklist for knowledge bases

A Markdown export is editable and easy to review, but a valid file is not automatically a publishable knowledge base article. The last mile needs its own checks.

Markdown SOP publishing checklist for a knowledge base

Define the publishing destination first

Start with the system that will render the article. Repository documentation, a static-site generator and a hosted knowledge base may all accept Markdown while interpreting headings, tables, callouts and image paths differently. Record the supported dialect, the required directory structure and any front matter before exporting the SOP.

Choose one article owner and one source of truth. If people revise both the StepShot project and the published Markdown independently, the instructions and screenshots will eventually diverge. Decide which changes must return to the editable project and how a corrected export replaces the previous knowledge base source.

Review the procedure before the package

Confirm the audience, prerequisites, starting state and success condition. Each step should describe one observable action and result. Remove abandoned clicks, duplicate frames and incidental navigation. Check that headings create a useful outline when images are hidden, because readers and search tools need the text to carry the procedure.

Review privacy while the source is still editable. Crop unrelated areas, confirm every required redaction and inspect screenshots at full resolution. Names, email addresses, internal URLs, tokens, account identifiers and notifications can remain legible even when the main action looks harmless.

Keep the Markdown and image directory together

A StepShot Markdown export creates a .md file and a matching image directory. Treat them as one release unit. Move, rename, review and commit them together. Uploading only the Markdown can leave every visual step broken, while renaming the image folder after export can invalidate otherwise correct relative paths.

Open the raw Markdown and sample the image references. Watch for spaces, letter-case changes and path rewriting by the destination. Test from the same directory depth used in production instead of relying on a local editor that searches for missing files or resolves paths more generously than the publishing system.

StepShot settings for document branding and export presentation — Review document presentation before export, then verify the rendered Markdown in its real destination.

Check links and publication metadata

Test every internal and external link from the rendered preview. Relative links must resolve from the final article URL, not from the writer's workstation. Remove links to private drafts, temporary environments and local files. If the knowledge base requires a title, slug, description, owner or review date in front matter, validate those fields against its schema.

Use a stable slug and preserve redirects when an existing article moves. A clear title and short description help readers choose the right procedure, but metadata must not promise a capability the steps do not demonstrate. Record the software state or interface version the screenshots were checked against when that context matters.

Use version control as a review surface

Review the exported change as a diff. Text changes should be understandable, deleted images should be intentional and replacement screenshots should match the revised steps. Avoid committing unrelated exports in the same change, because a focused review makes it easier to spot an accidental deletion or unexplained instruction change.

Assign a reviewer who can perform the task rather than only proofread it. They should follow the published sequence in a clean starting state, confirm the expected result and flag assumptions that belong in prerequisites. Record approval according to the team's normal publishing process.

Verify the rendered article after publishing

Preview the exact knowledge base output on desktop and a narrow viewport. Confirm the heading hierarchy, code formatting, image order, captions and readable image scale. Check that no navigation, access-control banner or theme style obscures a step. Then open the final URL in the access state used by its intended audience.

StepShot for macOS 14 and later keeps capture, editing and export local by default. It exports Markdown with a matching image directory, while Free exports include the first 10 captured steps and paid plans remove that step limit. Compare the current limits on pricing, review the export guide, or see the broader feature set before choosing a publishing workflow.