Markdown Mermaid Writing

<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->

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-style Markdown; verify the exact host and export pipeline. Reviewed: 2026-10-01 against CommonMark 0.31.2, GFM, and current GitHub formatting documentation.

Heading counts, emoji, separators, and citation placement below are optional house style. They are not Markdown conformance rules and do not override a requested format or an existing project/journal style. Tables and task lists are GFM extensions; footnotes, Mermaid, HTML details, and generated heading anchors depend on the host. 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

🗂️ Optional repository records

Markdown can preserve portable decision records and report snapshots. The issue, PR, and kanban templates support projects that choose file-based records; they do not change an existing tracker workflow or automatically synchronize with GitHub, GitLab, or another service. Preserve the project's actual source of truth and link to the live record when needed. Writing a file does not create an issue, post a comment, or update a board.

See File conventions for suggested names.

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

• Indent nested items under the parent item text — commonly 2 spaces after - and 3 after 1. . Marker width matters; a universal 2-space rule breaks ordered lists

• 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 — resolve them from the containing Markdown file, including copied templates

• Full URLs for external links — always https://

Footnote citations

Cite external factual claims with sources that support them. Use footnotes if the destination supports them; otherwise use inline/reference links or the required citation style. A citation must support the claim, not merely point to a related page. Explicitly label synthetic data and distinguish it from measurements; never invent references.

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

• Optional house style: follow with --- if the extra separator improves clarity

• GitHub supports Markdown inside details with blank lines around the Markdown content. Other renderers may sanitize HTML or leave it unparsed; preview the exported result

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

Use Mermaid for structural relationships when it improves understanding. Use data-driven plotting for quantitative figures that need exact geometry, uncertainty, or a journal-specific format.

When to add a diagram

If a diagram helps the reader, use the table to select a type and verify host support:

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. A short paragraph or data table can be clearer for a small amount of information.

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

The renderer supports every diagram type. ← Which renderer/version?

✅ Fix: Add footnote

GitHub documents Mermaid code blocks and an `info` diagram for checking its Mermaid version[^1].

[^1]: GitHub Docs. "Creating diagrams." https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams

❌ 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