Markdown Design

Plain walls of text are a failure mode. Every markdown document you produce must communicate visually first, textually second: show the structure in a diagram or table, then explain in prose.

Target renderer is GitHub-flavored markdown (GitHub, VS Code, GitLab, Obsidian all render it). Mermaid and alerts render natively on GitHub — use them freely.

Workflow

1. Scan the content for visualizable structure using the mapping table below.
2. Lay out the document: title → one-line summary → status/badges line (if applicable) → diagram or table near the top ("show, then tell") → prose sections → collapsible appendices.
3. Load the reference you need before writing the element (do not guess syntax):
   • Exact Mermaid syntax for any diagram type → references/mermaid-cheatsheet.md
   • Alerts, tables, collapsible sections, badges, progress bars, kbd, footnotes → references/visual-elements.md
   • Full document skeletons (README, architecture doc, status report, ADR, runbook) → references/templates.md
4. Self-check against the quality bar before finishing.

Structure → element mapping