claude-scientific-skills/scientific-skills/markdown-mermaid-writing/references/markdown_style_guide.md

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

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

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:

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

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

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

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

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:

---

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

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 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
Who talks to whom and when (API calls, messages)	Sequence diagram	sequence.md
Class hierarchy, type relationships, interfaces	Class diagram	class.md
Status transitions, entity lifecycle, state machine	State diagram	state.md
Database schema, data model, entity relationships	ER diagram	er.md
Project timeline, roadmap, task dependencies	Gantt chart	gantt.md
Parts of a whole, proportions, distribution	Pie chart	pie.md
Git branching strategy, merge/release flow	Git Graph	git_graph.md
Concept hierarchy, brainstorm, topic map	Mindmap	mindmap.md
Chronological events, milestones, history	Timeline	timeline.md
User experience, satisfaction scores, journey	User Journey	user_journey.md
Two-axis comparison, prioritization matrix	Quadrant chart	quadrant.md
Requirements traceability, compliance mapping	Requirement diagram	requirement.md
System architecture at varying zoom levels	C4 diagram	c4.md
Flow magnitude, resource distribution, budgets	Sankey diagram	sankey.md
Numeric trends, bar charts, line charts	XY Chart	xy_chart.md
Component layout, spatial arrangement, layers	Block diagram	block.md
Work item tracking, status board, task columns	Kanban board	kanban.md
Binary protocol layout, data packet format	Packet diagram	packet.md
Cloud infrastructure, service topology, networking	Architecture diagram	architecture.md
Multi-dimensional comparison, skills, radar analysis	Radar chart	radar.md
Hierarchical proportions, budget breakdown	Treemap	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:

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

Document type	Template	Best for
Presentation / briefing	presentation.md	Slide-deck-style documents with speaker notes, structured sections, and visual flow
Research paper / analysis	research_paper.md	Data-driven analysis, literature reviews, methodology + findings with heavy citations
Project documentation	project_documentation.md	Software/product docs — architecture, getting started, API reference, contribution guide
Decision record (ADR/RFC)	decision_record.md	Recording why a decision was made — context, options evaluated, outcome, consequences
How-to / tutorial guide	how_to_guide.md	Step-by-step instructions with prerequisites, verification steps, and troubleshooting
Status report / executive brief	status_report.md	Progress updates, risk summaries, decisions needed — for leadership and stakeholders
Pull request record	pull_request.md	PR documentation with change inventory, testing evidence, rollback plan, and review notes
Issue record	issue.md	Bug reports (reproduction steps, root cause) and feature requests (acceptance criteria, user stories)
Kanban board	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

## 📚📊📈 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