Style guide

The short version: write for future-you at 2 AM, not for strangers. You already know what the thing does; what you need is why it exists and what breaks it.

Structure of an entry

Required sections, in this order:

1. Frontmatter — title, description (search uses these)
2. Source reference — links to the canonical code. Always first, above any prose. Use the <SourceRef> component (see below) for a polished metadata strip, or the older > **Source:** ... blockquote if you prefer plain markdown.
3. What it is — one sentence. No more.
4. Why it exists — the backstory. What was there before? What problem did it solve? This is the highest-value section; don’t skimp.
5. Live — <Component client:load /> if the thing is browser-renderable
6. Code — the interesting part. A whole file dump is not code explanation — it’s file-copying.
7. How it’s used — bulleted list of projects + call sites. Helps future-you grep back to real usages.
8. Gotchas — what breaks, what’s surprising, what you already had to debug once.

Optional sections: Performance notes, Related entries, Alternatives considered.

Categories — what goes where

Folder	What belongs	Litmus test
components/	UI primitives and composite components	Does it take props and return JSX?
patterns/	Architectural ideas that appear in >1 project	Could I apply this to a project I haven’t built yet?
snippets/	Self-contained fragments (not a full component, not a pattern)	Is it under ~40 lines and solves one problem?
projects/	Whole-project architecture tours	Is this a one-pager explaining how everything fits?

If it doesn’t fit, it’s probably too broad. Split it.

The src/examples/ rule

Example files are teaching artifacts, not mirrors of production code.

• Drop: auth wiring, error boundaries, telemetry, app-specific context providers, feature flags
• Keep: the shape of the idea, enough that the live render actually runs
• Always: provenance comment at the top pinning the source:

  artifex/frontend/src/components/PhotoViewer.jsx

  // Simplified for the wiki: removed AuthContext, inlined button styles.

Drift between the example and the real source is fine. The entry teaches the idea, not the exact current implementation.

Components you can import

The wiki ships a few Astro components you can import into any MDX entry.

<SourceRef> — the top-of-entry metadata strip

import SourceRef from '../../../components/SourceRef.astro';

<SourceRef
  repo="atrium"
  path="backend/lib/projectRegistry.js"
  commit="9f24423"
  category="Pattern — identity"
/>

Renders as an amber-tinted pill with a GitHub icon, clickable path, commit SHA badge, and category label. Alternative: <SourceRef href="..." label="..." /> for links outside GitHub.

<Gotcha> — high-severity callouts

import Gotcha from '../../../components/Gotcha.astro';

<Gotcha title="Migration order is load-bearing">
  Back up live data BEFORE the first `git pull`, or the seed will overwrite admin edits.
</Gotcha>

Variants: warning (default, amber), danger (red), performance (blue), security (purple). Use sparingly — <Gotcha> is for the one or two caveats per entry that most deserve a reader’s attention. Ordinary gotchas stay as bullet points.

Starlight’s built-in <Aside>

For general callouts (note, tip, caution, danger), Starlight’s built-in <Aside> works and is already styled to match the theme:

import { Aside } from '@astrojs/starlight/components';

<Aside type="tip" title="Optional title">
  The actual content.
</Aside>

Tone

Reference-manual, not dev-blog. The voice on notes.r-that.com is the reference — match it.

Shape of a paragraph:

• **Topic** — short declarative descriptor. as the lead line of a section.
• Short paragraphs, one idea each. Complete thoughts.
• Em dashes as connectors — they do the work of semicolons.
• Declarative third-person-ish. “The registry exposes…” not “I built a registry that…”.

Explaining problems and fixes:

• **The problem:** / **The fix:** blocked structure, not prose arc.
• State facts and consequences. Skip the story of discovering them.
• Procedures get numbered step headers: 1. Install the essentials, 2. Configure the drop-in.

Away from:

• Narrative first-person. “I rebranded X”, “we tried Y first”, “ask me how I know”.
• Snarky asides. The wiki is reference material; the reader is looking something up, not reading a blog.
• Arc writing — “we tried X, it broke, so we switched to Z”. Replace with **What breaks:** X. **Why:** Y. **Use instead:** Z.

Still applies:

• No marketing voice. No “elegantly”, “simply”, “robust” — if the word would survive being deleted, delete it.
• Explain why more than what. Code already shows what.
• First person is OK when unavoidable for traceability (“my word-boundary match is liberal”) — but default to declarative.

When to write a new entry vs. update an existing one

• Same idea, different project → update the existing. Add a bullet to “How it’s used”.
• Genuinely new concept → new entry. Cross-link related ones at the bottom.
• Edge case of an existing pattern → a new section inside the existing entry, not a new entry.

If you’re unsure, err toward updating. Drift across fragmented entries is worse than a longer entry with cross-references.

Before you commit

• Build passes (npm run build)
• Sidebar auto-generation picked up the new file (check npm run dev)
• If you added src/examples/..., the live render actually works
• You’ve linked the Source repo/path at the top
• “Why it exists” has at least 2 sentences of real backstory

That’s it. This guide itself follows the rule: short, direct, future-you is the audience.