docs-page-style
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.