800-markdown

Markdown Documentation Gates

This rule owns mandatory Markdown policy only. Use the documentation standards skill (${HANDBOOK_ROOT}/skills/documentation-standards/SKILL.md) for document design, generated PNG diagrams, templates, ADRs, and writing workflows.

Structure and Proportionality

• Start standalone documents with one clear H1 and use a logical heading hierarchy without skipped levels.
• Add a table of contents, conclusion, alert, or diagram only when the document's complexity benefits from it. Do not force ceremony onto a short note or changelog entry.
• Use lists for sequences or sets and tables only when comparison across aligned columns is materially clearer.
• Avoid decorative emojis in professional technical documentation.

Prose and Code

• Keep each prose paragraph on one source line and let the renderer soft-wrap it. Do not hard-wrap prose at a fixed column.
• Break lists, tables, front matter, code, and diagrams only as their syntax requires.
• Use fenced code blocks with the correct language identifier and complete, safe examples.
• Do not use comments, headings, or callouts as decoration or to repeat nearby prose.
• Never author Unicode em dash (U+2014) or en dash (U+2013) characters. Use commas, colons, parentheses, semicolons, or ASCII hyphens instead. Preserve opaque external data only when exact bytes matter.

Links and Navigation

• Navigational URLs and repository paths must be clickable Markdown links with descriptive text; do not wrap links intended for navigation in backticks.
• Ordinary project documentation uses portable repository-relative links for same-repository navigation.
• Handbook-internal cross-file links use ${HANDBOOK_ROOT}/... so agents working in another repository resolve the correct source.
• Literal URL or path values shown as configuration, syntax, logs, or examples may use inline code.
• Verify changed links and anchors.

Alerts and Diagrams

• Use only supported GitHub alerts: NOTE, TIP, IMPORTANT, WARNING, and CAUTION.
• Keep alerts concise and place them next to the relevant instruction.
• Do not author Mermaid diagrams in Markdown or MDX.
• Add a diagram only when a relationship, sequence, state, hierarchy, or timeline is clearer visually than in short prose.
• Create an images/ directory beside the Markdown file, generate the diagram as a descriptively named PNG inside that directory, and embed it with meaningful alt text through a portable relative path such as images/request-flow.png.
• Do not create an images/ directory when the document does not need an image.
• Keep diagrams focused and readable at the rendered size. Exclude secrets, sensitive data, internal credentials, and unnecessary production identifiers.
• Verify that every referenced image exists, renders correctly, and matches the surrounding explanation before completion.