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.

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 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 communicate this better than text?
6. Add collapsible sections → For supplementary detail, speaker notes, or lengthy context
7. Verify → Run through the quality checklist

---

Core Principles

---

🗂️ 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

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 — the PR description IS this file
• Issue record — bug reports and feature requests as repo files
• Kanban board — sprint/project boards that merge with your code

See File conventions 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:

# 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

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

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:

> **Definition:** A _load balancer_ distributes incoming network traffic
> across multiple servers to ensure no single server bears too much demand.

For warnings and callouts:

> ⚠️ **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

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

✅ 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

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 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:

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

![Descriptive alt text for screen readers](images/architecture_overview.png)
_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:

See the Mermaid Style Guide 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, responsibi