docs-page-style · git:20260902.0a7a751 · 2026-09-02 · sha256 ecfdf79e389184d6
docs-page-style git:20260902.0a7a751A
Immutable. This exact content is served forever at /api/v1/blob/ecfdf79e389184d6.
---
name: docs-page-style
description: >-
House style and structure for uploads.sh documentation pages — the MDX
subject pages under apps/web/src/content/docs/ (and the docs.astro hub) 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/content/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. Each subject page is one `.mdx` file in the
`docs` content collection (`apps/web/src/content/docs/`), rendered through
`DocsLayout` by the `apps/web/src/pages/docs/[...slug].astro` route: you write
Markdown prose, fenced code blocks, and a small, fixed vocabulary of HTML
wrappers and components. The hub page (`apps/web/src/pages/docs.astro`) is still
a plain Astro page — it is a card index, not prose. 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 (`pnpm build` in `apps/web`).
## Adding or editing a page
A new subject page is a new `.mdx` file in `apps/web/src/content/docs/`. The
filename is the URL slug (`galleries.mdx` → `/docs/galleries`); the left nav,
the prev/next chain, and the static path all derive from its frontmatter, so
there is no route, nav, or pagination edit to make.
```yaml
---
title: Galleries # <title> and og/twitter title
description: … # meta description
heading: Galleries # the <h1>
tagline: … # one line under the <h1>
navLabel: Galleries # sidebar label (often shorter than heading)
navSlug: galleries # active-state key
navOrder: 2 # sidebar order AND the prev/next chain
toc: # optional "on this page" rail; omit it and no rail renders
- { id: what, label: What a gallery is }
---
```
`navOrder` is the whole ordering story: the sidebar lists entries in that order,
and the prev/next footer walks the same sequence, wrapping through the `/docs`
hub at both ends. Inserting a page means renumbering the ones after it.
MDX gotchas worth knowing before you write:
- Leave a blank line after an opening `<section …>` tag and before its `</section>`
so the prose inside is parsed as Markdown.
- Use `<div class="note">`, not `<p class="note">`: MDX wraps multi-line children
in their own `<p>`, and a `<p>` inside a `<p>` is invalid.
- Never let an inline component or `{expression}` start a line inside a
paragraph — MDX reparses it as a block and splits the sentence around it. This
is why `*.mdx` is excluded from `oxfmt` (see `.oxfmtrc.json`): a reflow would
do exactly that. Wrap prose by hand.
## 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
<p>Galleries collect related media behind one public link. With a gallery you can:</p>
<ul>
<li><a href="/docs/…">Group screenshots</a> into an ordered set.</li>
<li>Share the whole set with one URL.</li>
<li>Link the gallery to a PR or issue.</li>
</ul>
```
**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 "Agents take screenshots long before a pull request exists, and
GitHub's own attachments only work inside GitHub" — 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
<p class="pointer">
Already have a PR open? Use <code>uploads attach</code> instead —
<a href="/docs/attach-pull-request-images">see the walkthrough <span class="go">→</span></a
>.
</p>
```
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 (an ` ```ansi ` 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.
## Code blocks
Fenced blocks are rendered by [Expressive Code](https://expressive-code.com/)
(configured in `apps/web/src/lib/expressive-code-options.mjs`). The language tag
is the affordance — three conventions carry what the old hand-rolled `.cmd` and
`.block` markup used to:
| Fence | Renders as | Copy button |
| ------------------------- | ------------------------------------------------------------ | ----------- |
| ` ```bash ` | A command, with a `$ ` prompt drawn in the gutter | yes |
| ` ```ansi ` | Terminal output in a **terminal frame** (titlebar chrome) | no |
| ` ```text ` | A plain block — slash commands typed into an agent, snippets | yes |
| ` ```yaml ` / ` ```json ` | A syntax-highlighted config example | yes |
Frames add hierarchy where a bare panel would read flat:
- `ansi` blocks get terminal chrome automatically (configured in
`expressive-code-options.mjs`). Add `title="uploads staged"` to name the
command that produced the output — use the command the surrounding prose
already names, never an invented one. Untitled is fine for catalogs.
- Config/file examples opt into an editor frame per-fence with
`title=".uploads.yml" frame="code"` — the title is the filename the reader
will save. A paste-into-your-instructions snippet works the same way
(` ```md title="AGENTS.md" frame="code" `) and keeps its copy button.
- Commands stay bare panels (`$ ` prompt is the affordance); don't wrap a
one-liner in terminal chrome.
- **A command shown together with its output is ONE `ansi` terminal block**,
not a `bash` block followed by an `ansi` block — the split reads as two
unrelated artifacts. Write the command as a literal `$ command` first line
(the only place a literal `$` is allowed — `ansi` has no copy button, so
nothing dirty gets copied) and title the frame with the command name:
` ```ansi title="uploads staged" `.
The `$ ` prompt is CSS, not source text, so the copy button still yields a clean
command. Never write the `$` yourself. Comments (`# …`) inside a `bash` block are
stripped from the copied text automatically.
Config-file examples get syntax highlighting: a real `.uploads.yml` or JSON
snippet goes in a ` ```yaml ` / ` ```json ` fence, not a plain block.
Highlighting makes the keys and values pop out from explanatory comments.
## Copy-affordance rule
A copyable block 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 a ` ```bash ` block** for commands the reader genuinely pastes: the
install line, the golden-path command, a long `npx …` one-off.
- **Use inline `` `code` ``** 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 copyable command blocks, 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 copyable command blocks
reads as a wall of buttons. Put them in a single non-copyable ` ```ansi `
block instead, with the `# comment` aligned:
````
```ansi
uploads list # see your files
uploads delete <key> # remove a file
uploads usage # storage used by your workspace
```
````
Reserve ` ```bash ` 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.
**Genuinely equivalent alternatives go in tabs, not stacked blocks.** When one
action has two interchangeable entry points (the two ways to bake annotations
onto a capture, say), wrap them in `<Tabs>` / `<TabItem>` from
`apps/web/src/components/docs/`:
````mdx
<Tabs syncKey="annotate-entry-point">
<TabItem label="screenshot --annotate">
```bash
uploads screenshot … --annotate ./callouts.json
```
````
</TabItem>
</Tabs>
```
Groups sharing a `syncKey` switch together across the page, and the choice is
remembered per browser. Tabs are for real alternatives only — never a sequence of
steps, and never an invented variant of a command.
## Inline-code rule
Inline `<code>` is for **short identifiers and single tokens** — a command verb,
a flag, a package name, a path like `/g/<id>`. 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 ` ```bash ` 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 |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<section class="lead" id="…">` | The first section (no top divider under the page title). |
| `<section id="…">` | Every subsequent section; gets a top divider automatically. |
| `<h2>` with an `<a class="anchor" href="#id">#</a>` 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. |
| `<h3>` | Sub-heading within a section (e.g. a card title, a labelled step). |
| ` ```bash ` fence | A copyable command. The `$ ` prompt is drawn by CSS — never type it. A trailing `# comment` is stripped from the copied text. |
| ` ```ansi ` fence | Multi-line, **non-copyable** output or a reference command listing. Only for real, reproducible output. |
| ` ```text ` fence | A copyable non-shell line — a slash command typed into an agent, an instructions-file snippet. |
| `<Tabs>` / `<TabItem label="…">` | Two or more genuinely equivalent commands. `syncKey` links groups across the page. Not for sequences of steps. |
| `<div class="cards">` + `<a class="card">` | The "explore" grid of links to subject pages. Each card: `<h3>Title <span class="go">→</span></h3>` + one-sentence `<p>`. Trim to the highest-intent destinations rather than listing everything. |
| `<div class="note">` | A muted aside — the place for asides, "more:" link lists, and edge cases pulled out of the main flow. |
| `<div class="pointer">` | A demoted secondary-command line under the golden path (styled quieter than body text). Name only the verb inline; link to where it's covered in full. |
| `<div class="callout">` | An accent-tinted contextual banner near the top of a page (e.g. "landed here from a bot comment?"). Use sparingly, for orientation the reader needs before the content. |
| `<GithubAppInstalledBanner />` | The green post-install success banner, revealed by a `?setup_action=…` query param (GitHub App page only). Don't add new ones without the matching reveal logic. |
| `<table>` | Reference/comparison data (e.g. plans, limits). The natural form for a reference page — prefer it over prose for anything grid-shaped. |
| _(prev/next footer)_ | Generated from `navOrder` by the `[...slug].astro` route — don't hand-write one. |
| `<GhComment />` | A styled mock GitHub comment (avatar + bubble), for showing what a posted comment looks like. Specialised — only where a page illustrates GitHub output. |
| `` `code` `` | Short inline identifiers (see the inline-code rule). |
| `<span class="go">→</span>` | The trailing arrow on card titles and pointers. |
Page-specific markup that doesn't generalize (a mock wireframe, a data table fed
from code) belongs in a small `.astro` component under
`apps/web/src/components/docs/`, imported by the MDX — not inlined as a slab of
HTML in the prose.
The canonical example of all of this working together is
`apps/web/src/content/docs/attach-pull-request-images.mdx` (fenced-block
conventions, tabs, an imported wireframe component) alongside
`apps/web/src/pages/docs.astro` (the hub page: intro + capability list,
install-first ordering, the golden-path-plus-pointer pattern, and a trimmed card
grid). Read one of them before reworking a subject page.
## Hard constraints
- **Don't invent facts.** Every command, flag, URL, and capability must already
exist on the page, a sibling docs page, or the CLI. When unsure, check a sibling
page under `apps/web/src/content/docs/` rather than guessing.
- **Reuse the vocabulary above.** These are shared styles in `DocsLayout`; a new
class means new CSS and drift. Flag it explicitly if you truly need one.
- **Keep the page valid MDX** so it compiles, and verify it renders in the
browser preview (the `web` dev server) when you can — check the resting state is
calm and scannable, not just that it builds.