--- name: docs-page-style description: >- House style and structure for uploads.sh documentation pages — the Astro pages under apps/web/src/pages/docs/ (and docs.astro) built on DocsLayout. Use this whenever you write, restructure, trim, or review a docs page: requests like "clean up the galleries docs", "this docs page has too much prose", "rework the agents page", "the flow on /docs/comment-config feels complicated", "make the reference page scannable", or any edit to a file under apps/web/src/pages/docs/. Encodes the page structure (understand → set up → do), the Stripe-style intro voice, the copy-affordance and inline-code rules, the prose diet, and the DocsLayout component vocabulary, so every docs page reads like one deliberate, scannable system rather than a wall of prose. Reach for it even mid-task when you notice a docs page drifting toward heavy paragraphs, fabricated terminal output, or a copy button on every line. --- # uploads.sh docs page style These pages teach a developer (or their agent) to do one thing with the `uploads` CLI and then get out of the way. They are Astro pages built on `DocsLayout`, not Markdown — so you work in HTML using a small, fixed component vocabulary. The goal is a page that reads like reputable dev-tool docs (Stripe, Vercel, Wrangler): one short orientation, then commands you can actually run, with prose used only as connective tissue. The failure mode to fight is the opposite: heavy paragraphs, an example for every variation, a copy button on every line, and setup buried below usage. That reads as "complicated" even when every sentence is individually fine — because the _structure_ makes the reader work. ## How to approach a page 1. **Read the page and identify the ONE thing it's for.** Everything else is secondary and should be demoted or linked out, not given equal weight. 2. **Decide the page's job.** A hub/landing page (`docs.astro`) _triages and links_ — it should not re-teach what a subject page already covers. A subject page _walks through one workflow_. Don't duplicate a worked example that lives on another page; link to it instead. 3. **Order it: understand → set up → do.** A short "what/why", then install or prerequisites, then the golden-path command. A reader should be able to run the first real command without scrolling back up to find setup. 4. **Pick one golden path.** If there are two ways to do the thing, show the more universal one as the worked example and demote the other to a one-line pointer (see the pattern below). Never present two competing commands as parallel entry points — that fork is the single most common source of "this feels complicated." 5. **Apply the prose, copy, and inline-code rules** below to what's left. 6. **Verify it renders.** Reuse only the existing component classes, keep every command/flag/link real (never invent one — check a sibling page or the CLI), and confirm the page still compiles. ## Structure & voice ### Intro: one sentence, then a capability list — not paragraphs Lead with what the tool/feature _does for the reader_, verb-first, then (if scope needs conveying) a short bulleted capability list where each bullet links to the relevant page. This is the Stripe pattern: the copy reads like a spec sheet, not a pitch. No scene-setting ("In this guide…", "uploads.sh is a service that…"), no adjectives, no wind-up. **Prefer:** ```html

Galleries collect related media behind one public link. With a gallery you can:

``` **Avoid:** a two-sentence throat-clear before the reader learns what the page is for, or a second explanatory paragraph _after_ the first command (the reader wants to act, not read more). The thing to cut is _throat-clearing_ ("In this guide…", "uploads.sh is a service that…"), not substance. A concrete _why_ — a real constraint the tool exists to solve, like "GitHub has no API for file uploads, so agents can't include screenshots in pull requests" — earns its two or three sentences, because it tells the reader what problem they're actually solving. Lead with that when the page has one; keep it tight and get to the capability list. ### One golden path; demote the rest to a pointer Show the single most universal command as the worked example. A secondary command becomes a one-line pointer directly beneath it, linking to where it's covered in full: ```html

Already have a PR open? Use uploads attach instead — see the walkthrough →.

``` Note the pointer names only the _verb_ (`uploads attach`), not the full multi-argument invocation — that lives on the linked page. ### Prose diet - Cut throat-clearing lead-ins. Every sentence should state a fact or give an instruction. - One idea per sentence; split compound sentences glued with a comma or dash. - **Never fabricate terminal output.** Reputable docs don't show scripted output. Either show _real, verifiable_ output (a `.block` the reader can reproduce) or describe the effect in one sentence ("That uploads the file and prints a public URL."). Prefer the sentence. - Push troubleshooting and edge cases to the end, a `.note`, or a linked page — not into the main reading path. ## Copy-affordance rule A copy box (`.cmd`) signals "paste this verbatim." Putting one on every line trains the eye to see many equally-weighted "do this" boxes when usually only one command matters. So: - **Use `.cmd`** for commands the reader genuinely pastes: the install line, the golden-path command, a long `npx …` one-off. - **Use inline ``** for short, memorable, or illustrative commands — `uploads login`, `uploads doctor`, a bare `npx`, a flag, a filename. These are steps you _read_, not snippets you paste. Rule of thumb: **one copy target per action, not per line.** A typical page has one to three copy boxes, not one per command mentioned. **A reference list of sibling commands is one block, not N copy rows.** When a section just enumerates related commands (a "here's the command surface" menu, e.g. `list` / `delete` / `usage` / `--help`), a stack of `.cmd` copy rows reads as a wall of buttons. Put them in a single non-copyable `.block` instead — command in a `` (brighter), the `# comment` aligned in the muted base color: ```html 
uploads list          # see your files
uploads delete <key>  # remove a file
uploads usage         # storage used by your workspace
``` Reserve `.cmd` for the one or two commands in that section a reader actually runs in sequence (an install line, a golden path) — not the whole catalog. ## Inline-code rule Inline `` is for **short identifiers and single tokens** — a command verb, a flag, a package name, a path like `/g/`. This is near-universal in good docs. **Never set a full, multi-argument command inline** (e.g. `uploads attach ./before.png ./after.png` mid-sentence). It forces the reader to switch between prose cadence and monospace in one breath, wraps awkwardly across lines, and makes a runnable command look like a passing mention. Instead: - Put the full command in a `.cmd` block, **or** - Reference only the verb inline (`uploads attach`) and let the full form live in a block or on the linked page. Watch inline-code _density_ too: three or more inline-code spans crammed into one paragraph reads as busy. Split them across sentences, or move asides (like an `npx` alternative or a `doctor` check) into a `.note`. ## Component vocabulary (DocsLayout) Reuse these classes — don't invent new ones without a strong reason (note any new class you add and why). Headings and their `#` anchors, the copy-button behavior, the table of contents, and section dividers are all handled by `DocsLayout` automatically; you don't wire them up per page. | Element | Use for | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `
` | The first section (no top divider under the page title). | | `
` | Every subsequent section; gets a top divider automatically. | | `

` with an `#` inside | Section heading. The anchor sits in the left gutter and appears on hover; the whole heading is click-to-anchor. Keep the markup pattern; the layout styles it. | | `

` | Sub-heading within a section (e.g. a card title, a labelled step). | | `
` with `` + a `data-copy` `