Document formatting

Purpose: Define the canonical structure and style for all framework documents. Consistent formatting makes standards scannable, diffable, and professional across web and PDF rendering.

---

Contents

• Frontmatter
• Document structure
• Writing style
• Visual hierarchy
• Spacing rhythm
• Callouts
• Content format selection
• Diagrams
• Footer

---

Frontmatter

Every standard begins with YAML frontmatter containing these required fields:

---
tl;dr: "One-line summary of what this document covers."
version: 1.0.0
audience: engineering, product, design
applies_to: scope description
last_verified: 2026-03-15
---

Field	Purpose
tl;dr	One-line summary displayed in indexes and search results
version	Semver for tracking meaningful changes
audience	Who reads this document (comma-separated roles)
applies_to	Scope: which projects, teams, or domains this covers
last_verified	Date someone confirmed the content is still accurate

---

Document structure

Title and purpose

One H1 per document, matching the document's topic. Use sentence case ("Configure the database" not "Configure the Database").

Immediately after the H1, add a purpose blockquote:

> **Purpose:** One to three sentences explaining what this document does
> and why it exists.

Table of contents

Documents with more than four H2 sections include a table of contents:

## Contents

- [Section one](#section-one)
- [Section two](#section-two)

Heading hierarchy

• H2 for major sections
• H3 for subsections
• H4 maximum depth (never use H5 or H6)
• Never skip heading levels (no H2 followed directly by H4)

Horizontal rules

Use --- only between major H2 sections to create visual separation. Do not place horizontal rules between H3 subsections.

---

Writing style

These rules are drawn from the Google Developer Documentation Style Guide, Microsoft Writing Style Guide, and GitLab Documentation Standards.

Voice and tense

• Second person: "You can configure..." not "The user configures..."
• Active voice: "Run the command" not "The command should be run"
• Present tense: "This creates a file" not "This will create a file"

One sentence per line

Write one sentence per source line in markdown. This has zero impact on rendered output (markdown joins lines within a paragraph). It dramatically improves git diffs, merge conflict resolution, and line-level review comments.

<!-- Good -->
You can configure the database connection in `src/config/database.ts`.
The default timeout is 30 seconds.
Override it by setting the `DB_TIMEOUT` environment variable.

<!-- Bad -->
You can configure the database connection in `src/config/database.ts`. The default timeout is 30 seconds. Override it by setting the `DB_TIMEOUT` environment variable.

Formatting conventions

• Bold with ** for emphasis and UI element names
• Italic with _ for introducing terms and conditional annotations
• Backticks for file names, commands, values, environment variables, and code references
• Sentence case for all headings

List grammar

• Procedures and sequential steps use numbered lists
• Options, features, and non-sequential items use bullet lists
• Comparisons use tables
• All list items follow parallel grammatical structure (all start with verbs, or all are noun phrases)

---

Visual hierarchy

The single biggest factor in document readability is visual hierarchy — making it obvious where sections start, what the key terms are, and how items relate to each other. These patterns are drawn from Stripe, Tailwind, and Google documentation.

Bold lead terms

Every bullet and numbered list item that explains a concept starts with a bold term, followed by an em dash and the description. This creates scannable anchor points — readers can skim the bold terms without reading every line.

<!-- Good: scannable -->
- **Auth flows** — Login, logout, permission checks
- **Payment flows** — Checkout, subscription changes
- **Core business logic** — Access rules, pricing calculations

<!-- Bad: wall of text -->
- Auth flows like login, logout, permission checks
- Payment flows like checkout, subscription changes
- Core business logic like access rules, pricing calculations

When a bold-term item needs elaboration, add indented sub-items:

- **Route protection** — All non-public routes require Clerk middleware
    - Public routes: `/`, `/sign-in`, `/sign-up`, `/api/webhooks`
    - Everything else: `auth.protect()`
    - Middleware must be at project root (`middleware.ts`)

Indented sub-items

Use 4-space indentation for sub-items under a parent bullet or number. This creates clear visual nesting that separates the parent concept from its details.

1. **Capture immediately** — Create a Linear issue
    - Apply type label: `feature`, `bug`, `debt`, `idea`, `discovery`
    - Issue goes to Triage state
    - Priority and size are set during weekly triage

2. **Triage weekly** — Review all Triage issues every Monday
    - Promote to Backlog if actionable
    - Close or defer if not

Rules for nesting:

• 4 spaces per indent level (not 2 — 4 gives clear visual separation on GitHub)
• Maximum 3 levels of nesting (parent → child → grandchild)
• Don't nest if there's only one sub-item — fold it into the parent instead

Definition blocks

For key concepts that need a short explanation, use a bold term on its own line followed by the definition:

**Defense in depth**
Multiple overlapping security controls.
If one layer fails, the next catches it.

**Fail secure**
When something breaks, deny access by default.
Never fail open to unauthorized users.

This pattern works well for philosophy sections, glossaries, and principle statements.

When to use which pattern

Content	Pattern	Example
List of features/options	Bold lead + em dash	- **Auth** — Clerk middleware...
Feature with details	Bold lead + indented sub-items	Parent bullet + 4-space children
Key concept/principle	Definition block	Bold term, then prose lines
Step-by-step procedure	Numbered + bold lead + sub-items	1. **Step name** — Description
Comparison	Table	Side-by-side columns

---

Spacing rhythm

Consistent spacing creates visual hierarchy without relying on heavy decoration.

Element	Spacing
Before H2	Double blank line
Before H3 or H4	Single blank line
After any heading	Single blank line
Before/after code blocks	Single blank line
Before/after tables	Single blank line
Before/after lists	Single blank line

Some paragraph text.


## Major section

Content after the heading.

### Subsection

More content here.

---

Callouts

Use GitHub alert syntax for callouts. These render natively on GitHub and convert to styled admonition blocks in PDF output via the Lua filter.

> [!NOTE]
> Useful information users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information needed to achieve their goal.

> [!WARNING]
> Urgent info needing immediate attention.

> [!CAUTION]
> Risks or negative outcomes of certain actions.

Callout guidelines

• Maximum 2-3 callouts per page
• Place callouts near the content they relate to
• Keep callout text to 2-4 sentences
• Do not nest callouts inside other block elements

---

Content format selection

Choose the format that best serves the content type:

Content type	Format
Comparisons	Table
Sequential steps	Numbered list
Options or features	Bullet list
Detailed explanations	Prose paragraphs
Quick reference facts	Table or definition list
Status/category mappings	Table
Code examples	Fenced code block with language tag

---

Diagrams

When to use diagrams

• Pipeline flows, architecture overviews, org structures, spatial relationships
• Any concept where visual layout communicates relationships faster than text

When NOT to use diagrams

• Simple linear processes that a numbered list covers
• Lists of items with no spatial relationship

Placement and naming

• Store diagram files in the same directory as the document they illustrate
• Reference the diagram immediately after the heading it supports
• Name files as <doc-slug>-<descriptor>.png (e.g., linear-lifecycle-pipeline-flow.png)

Image requirements

• Alt text is required and must describe what the diagram shows, not just its title
• Target width: 1600-2400px
• Maximum file size: 500KB
• Format: PNG for generated diagrams, SVG for text-rendered diagrams

Tools

• /diagram skill for AI-generated diagrams (Excalidraw aesthetic)
• D2 for deterministic, text-rendered diagrams
• Excalidraw for hand-crafted whiteboard-style diagrams

---

Footer

Every document ends with:

1. A "Related standards" section listing cross-references to related documents
2. A horizontal rule
3. An italicized version line

## Related standards

- `standards/core/sdlc.md` -- Development lifecycle
- `standards/reference/org-chart.md` -- Agent roster by department

---

*Document Formatting v1.1 -- March 2026*

---

Related standards

• standards/core/sdlc.md -- Development lifecycle and eight phases
• standards/core/review-protocol.md -- Review protocol and finding format
• standards/reference/linear-formatting.md -- Linear comment templates

---

Document Formatting v1.1 -- March 2026