How guides are structured

Every guide follows the same skeleton, so once you’ve read one you can read any of them quickly.

Pages

guides/<slug>/
├── _guide.json     # metadata: label, blurb, order, status, tags, targetEnv
├── index.mdx       # page 1 — overview
├── 01-<slug>.mdx   # page 2, 3, … — one concept per page
└── 02-<slug>.mdx

• index.mdx — what the guide covers, who it’s for, prerequisites with versions, and a 60-second “does it work” check. Read this page first; it tells you whether to read the rest.
• Numbered pages — one thing per page. Each page opens with what you will be able to do by the end and stays within 600–1,500 words. If a topic needs more room, the guide gets another page — pages are cheap, sprawl is not.

The left sidebar shows the guide as a collapsible section with its pages nested inside; the current page and section are highlighted. Prev/next navigation at the bottom of each page stays within the guide — the last page of one guide doesn’t dump you into the next one.

What every page states

Two fields do most of the work of keeping this site honest:

• targetEnv (in _guide.json) — the exact environment every command was verified in: OS, versions, hardware. A guide written for CUDA 12.x on an A100 may not apply verbatim to your laptop.
• status / lastVerified (per page) — what was actually run, and when. See the status system.

If a page is not verified, a banner appears under the title: “Not executed on hardware — verify before relying on this.” Treat that as the author admitting exactly which parts of the page are unproven.

Conventions you can rely on

• Code blocks have a copy button and, where relevant, a filename caption. Syntax highlighting covers python, cpp, cuda, bash, and friends.
• Version pinning — commands and examples state versions, and _guide.json records them. If a guide says Triton 3.x, it was written and tested against a 3.x release.
• Callouts mark the important edges:
  • :::note — context worth knowing.
  • :::caution — things that look right but aren’t (the “gotcha” box).
  • :::danger — things that will cost you time or data if you skip them.
• Real output — terminal output shown in guides is captured from real runs, labelled with the hardware it came from. If you see a timing, it belongs to the stated machine, not a benchmark fairy.

How a guide gets published

1. A request arrives with audience, depth, target environment, and scope.
2. The guide is scaffolded, written page by page, and every runnable snippet is executed in the target environment (or honestly marked untested).
3. The site’s checks validate the structure, build it, and verify links.
4. On a green check it deploys; the search index is rebuilt on the server.

Guides are living documents: lastReviewed in _guide.json tracks when a guide was last checked against current versions. Stale guides get flagged by the weekly maintenance pass rather than silently rotting.