# Markdown Style Guide > **For AI agents:** Read this file for all core formatting rules. When creating any markdown document, follow these conventions for consistent, professional output. When a template exists for your document type, start from it — see [Templates](#templates). > > **For humans:** This guide ensures every markdown document in your project is clean, scannable, well-cited, and renders beautifully on GitHub. Reference it from your `AGENTS.md` or contributing guide. **Target platform:** GitHub Markdown (Issues, PRs, Discussions, Wikis, `.md` files) **Design goal:** Clear, professional documents that communicate effectively through consistent structure, meaningful formatting, proper citations, and strategic use of diagrams. --- ## Quick Start for Agents 1. **Identify the document type** → Check if a [template](#templates) exists 2. **Structure first** → Heading hierarchy, then content 3. **Apply formatting from this guide** → Headings, text, lists, tables, images, links 4. **Add citations** → Footnote references for all claims and sources 5. **Consider diagrams** → Would a [Mermaid diagram](mermaid_style_guide.md) communicate this better than text? 6. **Add collapsible sections** → For supplementary detail, speaker notes, or lengthy context 7. **Verify** → Run through the [quality checklist](#quality-checklist) --- ## Core Principles | # | Principle | Rule | | --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | **Answer before they ask** | Anticipate reader questions and address them inline. A great document resolves doubts as they form — the reader finishes with no lingering "but what about...?" | | 2 | **Scannable first** | Readers skim before they read. Use headings, bold, and lists to make the structure visible at a glance. | | 3 | **Cite everything** | Every claim, statistic, or external reference gets a footnote citation with a full URL. No orphan claims. | | 4 | **Diagrams over walls of text** | If a concept involves flow, relationships, or structure, use a [Mermaid diagram](mermaid_style_guide.md) alongside the text. | | 5 | **Generous with information** | Don't hide the details — surface them. Use collapsible sections for depth without clutter, but never omit information because "they probably don't need it." If it's relevant, include it. | | 6 | **Consistent structure** | Same heading hierarchy, same formatting patterns, same emoji placement across every document. | | 7 | **One idea per section** | Each heading should cover one topic. If you're covering two ideas, split into two headings. | | 8 | **Professional but approachable** | Clean formatting, no clutter, no decorative noise — but not stiff or academic. Write like a senior engineer explains to a colleague. | --- ## 🗂️ Everything is Code Everything is code. PRs, issues, kanban boards — they're all markdown files in your repo, not data trapped in a platform's database. ### Why this matters - **Portable** — GitHub → GitLab → Gitea → anywhere. Your project management data isn't locked into any vendor. Switch platforms and your issues, PR records, and boards come with you — they're just files. - **AI-native** — Agents can read every issue, PR record, and kanban board with local file access. No API tokens, no rate limits, no platform-specific queries. `grep` beats `gh api` every time. - **Auditable** — Project management changes go through the same PR review process as code changes. Every board update, every issue status change — it's all in git history with attribution and timestamps. ### How it works | What | Where it lives | What GitHub does | | -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Pull requests** | `docs/project/pr/pr-NNNNNNNN-short-description.md` | GitHub PR is a thin pointer — humans go there to comment on diffs, approve, and watch CI. The record of what changed, why, and what was learned lives in the file. | | **Issues** | `docs/project/issues/issue-NNNNNNNN-short-description.md` | GitHub Issues is a notification and comment layer. Bug reports, feature requests, investigation logs, and resolutions live in the file. | | **Kanban boards** | `docs/project/kanban/{scope}-{id}-short-description.md` | No external board tool needed. Modify the board in your branch, merge it with your PR. The board evolves with the codebase. | | **Decision records** | `docs/decisions/NNN-{slug}.md` | Not tracked in GitHub at all — purely repo-native. | ### The rule > 📌 **Don't capture information in GitHub's UI that should be captured in a file.** Approve PRs in GitHub. Watch CI in GitHub. Comment in GitHub. But the actual content — the description, the investigation, the decision — lives in a committed file. If it's worth writing down, it's worth committing. ### Templates for tracked documents - [Pull request record](markdown_templates/pull_request.md) — the PR description IS this file - [Issue record](markdown_templates/issue.md) — bug reports and feature requests as repo files - [Kanban board](markdown_templates/kanban.md) — sprint/project boards that merge with your code See [File conventions](#file-conventions-for-tracked-documents) for directory structure and naming. --- ## Document Structure ### Title and metadata Every document starts with exactly one H1 title, followed by a brief context line and a separator: ```markdown # Document Title Here _Brief context — project name, date, or purpose in one line_ --- ``` - **One H1 per document** — never more - Context line in italics — what this document is, when, and for whom - Horizontal rule separates metadata from content ### Heading hierarchy | Level | Syntax | Use | Max per document | | ----- | --------------- | ----------------------- | ------------------- | | H1 | `# Title` | Document title | **1** (exactly one) | | H2 | `## Section` | Major sections | 4–10 | | H3 | `### Topic` | Topics within a section | 2–5 per H2 | | H4 | `#### Subtopic` | Subtopics when needed | 2–4 per H3 | | H5+ | Never use | — | 0 | **Rules:** - **Never skip levels** — don't jump from H2 to H4 - **Emoji in H2 headings** — one emoji per H2, at the start: `## 📋 Project Overview` - **No emoji in H3/H4** — keep sub-headings clean - **Sentence case** — `## 📋 Project overview` not `## 📋 Project Overview` (exception: proper nouns) - **Descriptive headings** — `### Authentication flow` not `### Details` --- ## Text Formatting ### Bold, italic, code | Format | Syntax | When to use | Example | | ---------- | ------------ | --------------------------------------------- | ----------------------------------- | | **Bold** | `**text**` | Key terms, important concepts, emphasis | **Primary database** handles writes | | _Italic_ | `*text*` | Definitions, titles, subtle emphasis | The process is called _sharding_ | | `Code` | `` `text` `` | Technical terms, commands, file names, values | Run `npm install` to install | | ~~Strike~~ | `~~text~~` | Deprecated content, corrections | ~~Old approach~~ replaced by v2 | **Rules:** - **Bold sparingly** — if everything is bold, nothing is. Max 2–3 bold terms per paragraph. - **Don't combine** bold and italic (`***text***`) — pick one - **Code for anything technical** — file names (`README.md`), commands (`git push`), config values (`true`), environment variables (`NODE_ENV`) - **Never bold entire sentences** — bold the key word(s) within the sentence ### Blockquotes Use blockquotes for definitions, callouts, and important notes: ```markdown > **Definition:** A _load balancer_ distributes incoming network traffic > across multiple servers to ensure no single server bears too much demand. ``` For warnings and callouts: ```markdown > ⚠️ **Warning:** This operation is destructive and cannot be undone. > 💡 **Tip:** Use `--dry-run` to preview changes before applying. > 📌 **Note:** This requires admin permissions on the repository. ``` - Prefix with emoji + bold label for typed callouts - Keep blockquotes to 1–3 lines - Don't nest blockquotes (`>>`) --- ## Lists ### When to use each type | List type | Syntax | Use when | | --------- | ------------ | ----------------------------------------- | | Bullet | `- item` | Items have no inherent order | | Numbered | `1. step` | Steps must happen in sequence | | Checkbox | `- [ ] item` | Tracking completion (agendas, checklists) | ### Formatting rules - **Consistent indentation** — 2 spaces for sub-items (some renderers use 4; pick one, stick with it) - **Parallel structure** — every item in a list should have the same grammatical form - **No period at end** unless items are full sentences - **Keep items concise** — if a bullet needs a paragraph, it should be a sub-section instead - **Max nesting depth: 2 levels** — if you need a third level, restructure ```markdown ✅ Good — parallel structure, concise: - Configure the database connection - Run the migration scripts - Verify the schema changes ❌ Bad — mixed structure, verbose: - You need to configure the database - Migration scripts - After that, you should verify that the schema looks correct ``` --- ## Links and Citations ### Inline links ```markdown See the [Mermaid Style Guide](mermaid_style_guide.md) for diagram conventions. ``` - **Meaningful link text** — `[Mermaid Style Guide]` not `[click here]` or `[link]` - **Relative paths** for internal links — `[Guide](./README.md)` not absolute URLs - **Full URLs** for external links — always `https://` ### Footnote citations **Every claim, statistic, or reference to external work MUST have a footnote citation.** This is non-negotiable for credibility. ```markdown Markdown was created by John Gruber in 2004 as a lightweight markup language designed for readability[^1]. GitHub adopted Mermaid diagram support in February 2022[^2]. [^1]: Gruber, J. (2004). "Markdown." _Daring Fireball_. https://daringfireball.net/projects/markdown/ [^2]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ ``` **Citation format:** ``` [^N]: Author/Org. (Year). "Title." *Publication*. https://full-url ``` **Rules:** - **Number sequentially** — `[^1]`, `[^2]`, `[^3]` in order of appearance - **Full URL always included** — the reader must be able to reach the source - **Group all footnotes at the document bottom** — under a `## References` section or at the very end - **Every external claim needs one** — statistics, quotes, methodologies, tools mentioned - **Internal project links don't need footnotes** — use inline links instead ### Reference-style links (for repeated URLs) When the same URL appears multiple times, use reference-style links to keep the text clean: ```markdown The [official docs][mermaid-docs] cover all diagram types. See [Mermaid documentation][mermaid-docs] for the full syntax. [mermaid-docs]: https://mermaid.js.org/ 'Mermaid Documentation' ``` --- ## Images and Figures ### Placement and syntax ```markdown  _Figure 1: System architecture showing the three-tier deployment model_ ``` **Rules:** - **Inline with content** — place images where they're relevant, not in a separate "Images" section - **Descriptive alt text** — `![Three-tier architecture diagram]` not `![image]` or `![screenshot]` - **Italic caption below** — `*Figure N: What this image shows*` - **Number figures sequentially** — Figure 1, Figure 2, etc. if multiple images - **Relative paths** — `images/file.png` not absolute paths - **Reasonable file sizes** — compress PNGs, use SVG where possible ### Image naming convention ``` {document-slug}_{description}.{ext} Examples: auth_flow_overview.png deployment_architecture.svg api_response_example.png ``` ### When NOT to use an image If the content could be expressed as a **Mermaid diagram**, prefer that over a static image: | Scenario | Use | | -------------------------- | ------------------------------------------ | | Architecture diagram | Mermaid `flowchart` or `architecture-beta` | | Sequence/interaction | Mermaid `sequenceDiagram` | | Data model | Mermaid `erDiagram` | | Timeline | Mermaid `timeline` or `gantt` | | Screenshot of UI | Image (Mermaid can't do this) | | Photo / real-world image | Image | | Complex data visualization | Image or Mermaid `xychart-beta` | See the [Mermaid Style Guide](mermaid_style_guide.md) for diagram type selection and styling. --- ## Tables ### When to use tables - **Structured comparisons** — features, options, tradeoffs - **Reference data** — configuration values, API parameters, status codes - **Schedules and matrices** — timelines, responsibility assignments ### When NOT to use tables - **Narrative content** — use paragraphs instead - **Simple lists** — use bullet points - **More than 5 columns** — becomes unreadable on mobile; restructure ### Formatting ```markdown | Feature | Free Tier | Pro Tier | Enterprise | | ------- | --------- | -------- | ---------- | | Users | 5 | 50 | Unlimited | | Storage | 1 GB | 100 GB | Custom | | Support | Community | Email | Dedicated | ``` **Rules:** - **Header row always** — no headerless tables - **Left-align text columns** — `|---|` (default) - **Right-align number columns** — `|---:|` when appropriate - **Concise cell content** — 1–5 words per cell. If you need more, it's not a table problem - **Bold key column** — the first column or the column the reader scans first - **Consistent formatting within columns** — don't mix sentences and fragments --- ## Code Blocks ### Inline code Use backticks for technical terms within prose: ```markdown Run `git status` to check for uncommitted changes. The `NODE_ENV` variable controls the runtime environment. ``` ### Fenced code blocks Always specify the language for syntax highlighting: ````markdown ```python def calculate_average(values: list[float]) -> float: """Return the arithmetic mean of a list of values.""" return sum(values) / len(values) ``` ```` **Rules:** - **Always include language identifier** — ` ```python `, ` ```bash `, ` ```json `, etc. - **Use ` ```text ` for plain output** — not ` ``` ` with no language - **Keep blocks focused** — show the relevant snippet, not the entire file - **Add a comment if context needed** — `# Configure the database connection` at the top of the block --- ## Collapsible Sections Use HTML `

` for supplementary content that shouldn't clutter the main flow — speaker notes, implementation details, verbose logs, or optional deep-dives. ```markdown

💬 Speaker Notes

- Key talking point one - Transition to next topic - **Bold** emphasis works inside details - [Links](https://example.com) work too

--- ``` **Rules:** - **Collapsed by default** — the `

` tag collapses automatically - **Descriptive summary** — `💬 Speaker Notes` or `📋 Implementation Details` - **Blank line after `

` tag** — required for markdown to render inside the block - **ALWAYS follow with `---`** — horizontal rule after every `

` for visual separation - **Any markdown works inside** — bullets, bold, links, code blocks, tables ### Common collapsible patterns | Summary label | Use for | | --------------------- | ------------------------------------------------ | | 💬 **Speaker Notes** | Presentation talking points, timing, transitions | | 📋 **Details** | Extended explanation, verbose context | | 🔧 **Implementation** | Technical details, code samples, config | | 📊 **Raw Data** | Full output, logs, data tables | | 💡 **Background** | Context that helps but isn't essential | --- ## Horizontal Rules Use `---` (three hyphens) for visual separation: ```markdown --- ``` **When to use:** - **After every `

` block** — mandatory, creates clear separation - **After title/metadata** — separates document header from content - **Between major sections** — when an H2 heading alone doesn't create enough visual break - **Before footnotes/references** — separates content from citation list **When NOT to use:** - Between every paragraph (too busy) - Between H3 sub-sections within the same H2 (use whitespace instead) --- ## Approved Emoji Set One emoji per H2 heading, at the start. Use sparingly in body text for callouts and emphasis only. ### Section headings | Emoji | Use for | | ----- | -------------------------------------- | | 📋 | Overview, summary, agenda, checklist | | 🎯 | Goals, objectives, outcomes, targets | | 📚 | Content, documentation, main body | | 🔗 | Resources, references, links | | 📍 | Agenda, navigation, current position | | 🏠 | Housekeeping, logistics, announcements | | ✍️ | Tasks, assignments, action items | ### Status and outcomes | Emoji | Meaning | | ----- | ------------------------------------ | | ✅ | Success, complete, correct, approved | | ❌ | Failure, incorrect, avoid, rejected | | ⚠️ | Warning, caution, important notice | | 💡 | Tip, insight, idea, best practice | | 📌 | Important, key point, remember | | 🚫 | Prohibited, do not, blocked | ### Technical and process | Emoji | Meaning | | ----- | --------------------------------- | | ⚙️ | Configuration, settings, process | | 🔧 | Tools, utilities, setup | | 🔍 | Analysis, investigation, review | | 📊 | Data, metrics, analytics | | 📈 | Growth, trends, improvement | | 🔄 | Cycle, refresh, iteration | | ⚡ | Performance, speed, quick action | | 🔐 | Security, authentication, privacy | | 🌐 | Web, API, network, global | | 💾 | Storage, database, persistence | | 📦 | Package, artifact, deployment | ### People and collaboration | Emoji | Meaning | | ----- | ----------------------------------- | | 👤 | User, person, individual | | 👥 | Team, group, collaboration | | 💬 | Discussion, comments, speaker notes | | 🎓 | Learning, education, knowledge | | 🤔 | Question, consideration, reflection | ### Emoji rules 1. **One per H2 heading** at the start — `## 📋 Overview` 2. **None in H3/H4** — keep sub-headings clean 3. **Sparingly in body text** — for callouts (`> ⚠️ **Warning:**`) and key markers only 4. **Never in**: titles (H1), code blocks, link text, table data cells 5. **No decorative emoji** — 🎉 💯 🔥 🎊 💥 ✨ add noise, not meaning 6. **Consistency** — same emoji = same meaning across all documents in the project --- ## Mermaid Diagram Integration **Whenever content describes flow, structure, relationships, or processes, consider whether a Mermaid diagram would communicate it better than prose alone.** Diagrams and text together are more effective than either alone. ### When to add a diagram **Any time your text describes flow, structure, relationships, timing, or comparisons, there's a Mermaid diagram that communicates it better.** Scan the table below to identify the right type, then follow this workflow: 1. **Read the [Mermaid Style Guide](mermaid_style_guide.md) first** — emoji, color palette, accessibility, complexity management 2. **Then open the specific type file** — exemplar, tips, template, complex example | Your content describes... | Add a... | Type file | | ---------------------------------------------------- | ------------------------ | --------------------------------------------------- | | Steps in a process, workflow, decision logic | **Flowchart** | [flowchart.md](mermaid_diagrams/flowchart.md) | | Who talks to whom and when (API calls, messages) | **Sequence diagram** | [sequence.md](mermaid_diagrams/sequence.md) | | Class hierarchy, type relationships, interfaces | **Class diagram** | [class.md](mermaid_diagrams/class.md) | | Status transitions, entity lifecycle, state machine | **State diagram** | [state.md](mermaid_diagrams/state.md) | | Database schema, data model, entity relationships | **ER diagram** | [er.md](mermaid_diagrams/er.md) | | Project timeline, roadmap, task dependencies | **Gantt chart** | [gantt.md](mermaid_diagrams/gantt.md) | | Parts of a whole, proportions, distribution | **Pie chart** | [pie.md](mermaid_diagrams/pie.md) | | Git branching strategy, merge/release flow | **Git Graph** | [git_graph.md](mermaid_diagrams/git_graph.md) | | Concept hierarchy, brainstorm, topic map | **Mindmap** | [mindmap.md](mermaid_diagrams/mindmap.md) | | Chronological events, milestones, history | **Timeline** | [timeline.md](mermaid_diagrams/timeline.md) | | User experience, satisfaction scores, journey | **User Journey** | [user_journey.md](mermaid_diagrams/user_journey.md) | | Two-axis comparison, prioritization matrix | **Quadrant chart** | [quadrant.md](mermaid_diagrams/quadrant.md) | | Requirements traceability, compliance mapping | **Requirement diagram** | [requirement.md](mermaid_diagrams/requirement.md) | | System architecture at varying zoom levels | **C4 diagram** | [c4.md](mermaid_diagrams/c4.md) | | Flow magnitude, resource distribution, budgets | **Sankey diagram** | [sankey.md](mermaid_diagrams/sankey.md) | | Numeric trends, bar charts, line charts | **XY Chart** | [xy_chart.md](mermaid_diagrams/xy_chart.md) | | Component layout, spatial arrangement, layers | **Block diagram** | [block.md](mermaid_diagrams/block.md) | | Work item tracking, status board, task columns | **Kanban board** | [kanban.md](mermaid_diagrams/kanban.md) | | Binary protocol layout, data packet format | **Packet diagram** | [packet.md](mermaid_diagrams/packet.md) | | Cloud infrastructure, service topology, networking | **Architecture diagram** | [architecture.md](mermaid_diagrams/architecture.md) | | Multi-dimensional comparison, skills, radar analysis | **Radar chart** | [radar.md](mermaid_diagrams/radar.md) | | Hierarchical proportions, budget breakdown | **Treemap** | [treemap.md](mermaid_diagrams/treemap.md) | > 💡 **Pick the right type, not the easy type.** Don't default to flowcharts for everything — a timeline is better than a flowchart for chronological events, a sequence diagram is better for service interactions, an ER diagram is better for data models. Scan the table above and match your content to the most specific type. **If you catch yourself writing a paragraph that describes a visual concept, stop and diagram it.** ### How to integrate Place the diagram **inline with the related text**, not in a separate section: ````markdown ### Authentication Flow The login process validates credentials, checks MFA status, and issues session tokens. Failed attempts are logged for security monitoring. ‎```mermaid sequenceDiagram accTitle: Login Authentication Flow accDescr: User login sequence through API and auth service participant U as 👤 User participant A as 🌐 API participant S as 🔐 Auth Service U->>A: POST /login A->>S: Validate credentials S-->>A: ✅ Token issued A-->>U: 200 OK + session ‎``` The token expires after 24 hours. See [Authentication flow](#authentication-flow) for refresh token details. ```` **Always follow the [Mermaid Style Guide](mermaid_style_guide.md)** for diagram styling — emoji, color classes, accessibility (`accTitle`/`accDescr`), and type-specific conventions. --- ## Whitespace and Spacing - **Blank line between paragraphs** — always - **Blank line before and after headings** — always - **Blank line before and after code blocks** — always - **Blank line before and after blockquotes** — always - **No blank line between list items** — keep lists tight - **No trailing whitespace** — clean line endings - **One blank line at end of file** — standard convention - **No more than one consecutive blank line** — two blank lines = too much space --- ## Quality Checklist ### Structure - [ ] Exactly one H1 title - [ ] Heading hierarchy is correct (H1 → H2 → H3 → H4, no skips) - [ ] Each H2 has exactly one emoji at the start - [ ] H3 and H4 have no emoji - [ ] Horizontal rules after title metadata and after every `` block ### Content - [ ] Every external claim has a footnote citation - [ ] All footnotes have full URLs - [ ] All links tested and working - [ ] Meaningful link text (no "click here") - [ ] Bold used for key terms, not entire sentences - [ ] Code formatting for all technical terms ### Visual elements - [ ] Images have descriptive alt text - [ ] Images have italic figure captions - [ ] Images placed inline with related content (not in separate section) - [ ] Tables have header rows and consistent formatting - [ ] Mermaid diagrams considered where applicable (with `accTitle`/`accDescr`) ### Collapsible sections - [ ] `

` blocks have descriptive `

` labels - [ ] Blank line after `

` tag (for markdown rendering) - [ ] Horizontal rule `---` after every `

` block - [ ] Content inside collapses renders correctly ### Polish - [ ] No spelling or grammar errors - [ ] Consistent whitespace (no trailing spaces, no double blanks) - [ ] Parallel grammatical structure in lists - [ ] Renders correctly in GitHub light and dark mode --- ## Templates Templates provide pre-built structures for common document types. Copy the template, fill in your content, and follow this style guide for formatting. Every template enforces the principles above — citations, diagrams, collapsible depth, and self-answering structure. | Document type | Template | Best for | | ------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Presentation / briefing | [presentation.md](markdown_templates/presentation.md) | Slide-deck-style documents with speaker notes, structured sections, and visual flow | | Research paper / analysis | [research_paper.md](markdown_templates/research_paper.md) | Data-driven analysis, literature reviews, methodology + findings with heavy citations | | Project documentation | [project_documentation.md](markdown_templates/project_documentation.md) | Software/product docs — architecture, getting started, API reference, contribution guide | | Decision record (ADR/RFC) | [decision_record.md](markdown_templates/decision_record.md) | Recording why a decision was made — context, options evaluated, outcome, consequences | | How-to / tutorial guide | [how_to_guide.md](markdown_templates/how_to_guide.md) | Step-by-step instructions with prerequisites, verification steps, and troubleshooting | | Status report / executive brief | [status_report.md](markdown_templates/status_report.md) | Progress updates, risk summaries, decisions needed — for leadership and stakeholders | | Pull request record | [pull_request.md](markdown_templates/pull_request.md) | PR documentation with change inventory, testing evidence, rollback plan, and review notes | | Issue record | [issue.md](markdown_templates/issue.md) | Bug reports (reproduction steps, root cause) and feature requests (acceptance criteria, user stories) | | Kanban board | [kanban.md](markdown_templates/kanban.md) | Sprint/release/project work tracking with visual board, WIP limits, metrics, and blocked items | ### File conventions for tracked documents Some templates produce documents that accumulate over time. Use these directory conventions: | Document type | Directory | Naming pattern | Example | | ---------------- | ---------------------- | ------------------------------------------- | ----------------------------------------------------------------------- | | Pull requests | `docs/project/pr/` | `pr-NNNNNNNN-short-description.md` | `docs/project/pr/pr-00000123-fix-auth-timeout.md` | | Issues | `docs/project/issues/` | `issue-NNNNNNNN-short-description.md` | `docs/project/issues/issue-00000456-add-export-filter.md` | | Kanban boards | `docs/project/kanban/` | `{scope}-{identifier}-short-description.md` | `docs/project/kanban/sprint-2026-w07-agentic-template-modernization.md` | | Decision records | `docs/decisions/` | `NNN-{slug}.md` | `docs/decisions/001-use-postgresql.md` | | Status reports | `docs/status/` | `status-{date}.md` | `docs/status/status-2026-02-14.md` | ### Choosing a template - **Presenting to people?** → Presentation - **Publishing analysis or research?** → Research paper - **Documenting a codebase or product?** → Project documentation - **Recording why you chose X over Y?** → Decision record - **Teaching someone how to do something?** → How-to guide - **Updating leadership on progress?** → Status report - **Documenting a PR for posterity?** → Pull request record - **Tracking a bug or requesting a feature?** → Issue record - **Managing work items for a sprint or project?** → Kanban board - **None of these fit?** → Start from this style guide's rules directly — no template required --- ## Common Mistakes ### ❌ Multiple emoji per heading ```markdown ## 📚📊📈 Content Topics ← Too many ``` ✅ Fix: One emoji per H2 ```markdown ## 📚 Content topics ``` ### ❌ Missing citations ```markdown Studies show 73% of developers prefer Markdown. ← Where's the source? ``` ✅ Fix: Add footnote ```markdown Studies show 73% of developers prefer Markdown[^1]. [^1]: Stack Overflow. (2024). "Developer Survey Results." https://survey.stackoverflow.co/2024 ``` ### ❌ Wall of text without structure ```markdown The system handles authentication by first checking the JWT token validity, then verifying the user exists in the database, then checking their permissions against the requested resource... ``` ✅ Fix: Use a list, heading, or diagram ```markdown ### Authentication flow 1. Validate JWT token signature and expiration 2. Verify user exists in the database 3. Check user permissions against the requested resource ``` ### ❌ Images in a separate section ```markdown ## Content [paragraphs of text] ## Screenshots [all images grouped here] ← Disconnected from context ``` ✅ Fix: Place images inline where relevant ### ❌ No horizontal rule after collapsible sections ```markdown ### Next Topic ← Runs together visually ``` ✅ Fix: Always add `---` after `` ```markdown --- ### Next topic ← Clear separation ``` --- ## Resources - [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) · [Mermaid Style Guide](mermaid_style_guide.md) · [GitHub Basic Formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)