--- title: "Markdown Style Guide" description: "" type: tutorial canonical_url: https://claudary.paisolsolutions.com/tutorials/markdown-style-guide source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:30:46.645Z license: CC-BY-4.0 attribution: "Markdown Style Guide — Claudary (https://claudary.paisolsolutions.com/tutorials/markdown-style-guide)" --- # Markdown Style Guide ## Overview # 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 ![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](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, responsibi --- Source: [Claudary](https://claudary.paisolsolutions.com/tutorials/markdown-style-guide) · https://claudary.paisolsolutions.com