Markdown Style Guide

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

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

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:

```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 <details> for supplementary content that shouldn't clutter the main flow — speaker notes, implementation details, verbose logs, or optional deep-dives.

<details>
<summary><strong>💬 Speaker Notes</strong></summary>

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

</details>

---

Rules:

• Collapsed by default — the <details> tag collapses automatically
• Descriptive summary — <strong>💬 Speaker Notes</strong> or <strong>📋 Implementation Details</strong>
• Blank line after <summary> tag — required for markdown to render inside the block
• ALWAYS follow with --- — horizontal rule after every </details> for visual separation
• Any markdown works inside — bullets, bold, links, code blocks, tables

Common collapsible patterns

Horizontal Rules

Use --- (three hyphens) for visual separation:

---

When to use:

• After every </details> 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

Status and outcomes

Technical and process

People and collaboration

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 first — emoji, color palette, accessibility, complexity management
2. Then open the specific type file — exemplar, tips, template, complex example

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

### 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 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 </details> 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

• <details> blocks have descriptive <summary> labels
• Blank line after <summary> tag (for markdown rendering)
• Horizontal rule --- after every </details> 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.

File conventions for tracked documents

Some templates produce documents that accumulate over time. Use these directory conventions:

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

## 📚📊📈 Content Topics ← Too many

✅ Fix: One emoji per H2

## 📚 Content topics

❌ Missing citations

Studies show 73% of developers prefer Markdown. ← Where's the source?

✅ Fix: Add footnote

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

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

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

## Content

[paragraphs of text]

## Screenshots

[all images grouped here] ← Disconnected from context

✅ Fix: Place images inline where relevant

❌ No horizontal rule after collapsible sections

</details>
### Next Topic  ← Runs together visually

✅ Fix: Always add --- after </details>

</details>

---

### Next topic ← Clear separation

Resources

• GitHub Flavored Markdown Spec · Mermaid Style Guide · GitHub Basic Formatting