Turn Markdown Into a Reviewable Technical Demo

Markdown is easy to write, but a useful technical demo needs more than headings and fenced code. The reader should know what the example proves, which assumptions it makes, and how to reproduce the important result.

Open with the outcome rather than a history lesson. State the task, the expected behavior, and the environment in which you verified it. When a command modifies data, say so before the code block. When output is abbreviated, mark the omission instead of presenting it as literal output.

Use heading levels as structure, not visual sizing. A page should normally have one primary title, followed by sections and subsections in order. Descriptive link text is more useful than repeated “click here,” and a code block should declare its language so syntax highlighting does not guess.

## Verify the response

Run the read-only health check:

\`\`\`bash
curl --fail https://example.test/health
\`\`\`

Expected response: `{"status":"ok"}`.

Treat embedded HTML as executable content. A renderer that permits arbitrary HTML should isolate it just like an HTML playground. Links also deserve review: a polished Markdown page can still be a vehicle for phishing or unsafe downloads.

For long guides, include a small table of contents only when it helps navigation. Avoid repeating the same conclusion under multiple headings to manufacture length. Original value comes from the concrete decisions, limitations, and failure modes the author contributes.

Before sharing, follow every link, run every command in a safe environment, check narrow-screen code overflow, and remove secrets from examples. The rendered document should remain understandable even if optional images fail to load.

Define the Markdown contract

“Markdown support” is ambiguous until you name the parser, enabled extensions, and raw-HTML policy. Decide whether tables, task lists, footnotes, automatic links, and fenced-code metadata are part of the contract. Provide one fixture for each supported feature and one deliberately unsupported example. This prevents a reviewer from assuming that behavior in another Markdown product applies to yours.

Keep the source beside the rendered result. A split view makes whitespace, escaping, and nesting errors visible and helps distinguish parser behavior from CSS. Preserve line endings and indentation in the fixture. Reformatting the input before parsing may make the preview attractive while hiding a compatibility problem in pasted documents.

Treat rendering as a security boundary

Markdown can produce links, images, and sometimes raw HTML. Disable raw HTML unless the use case requires it; if it is enabled, sanitize the produced HTML with a maintained allowlist before inserting it into the document. Reject dangerous URL schemes and add safe attributes to external links. Do not rely on the parser alone to remove scripts, event handlers, SVG payloads, or malicious data URLs.

Test adversarial fixtures: encoded JavaScript URLs, broken tags, nested emphasis around links, enormous data images, and HTML that tries to escape its container. Render untrusted output in an isolated environment when possible. Security behavior belongs in the demo because it changes the product contract, not merely the deployment configuration.

Design readable output

Create explicit styles for headings, paragraphs, lists, blockquotes, tables, inline code, and fenced code. Limit prose width while allowing code and tables to scroll within their own containers. Ensure long URLs and unbroken strings cannot widen the whole page. Add visible focus styles to links and copy controls, and preserve sufficient contrast in syntax themes.

Use realistic content pressure: nested lists, multiple heading levels, a table wider than the viewport, a very long code line, and mixed Latin/CJK text. Verify heading order rather than choosing levels for visual size. If generated heading anchors are part of the experience, test duplicate headings and punctuation so links remain stable.

Verify deterministic and accessible behavior

The same source and configuration should produce the same safe output. Pin parser options and document any custom renderer. If syntax highlighting runs asynchronously, reserve space and ensure the unhighlighted code remains readable. Avoid mutating code text merely to highlight it; users may copy the rendered content and expect the original bytes.

Also test copy and selection across inline formatting, code blocks, and generated anchors. The visible document should remain useful when styles fail or highlighting is unavailable.

Keep these fixtures in version control and render them during upgrades. Compare both safe HTML output and the visible page, because a parser or sanitizer change can alter behavior without producing an obvious runtime error.

Inspect the accessibility tree for table headers, link names, list structure, and code controls. Test keyboard scrolling inside wide regions without creating a focus trap. Finally, record the parser version, extensions, sanitization rules, and known limitations alongside the shared example. That evidence lets another developer reproduce the result and update the contract deliberately.