Example

When to use it

Write an example when the code is the content — a pattern, an integration, a configuration worth copying whole. It is not:

• A how-to. A how-to is a procedure — actions across surfaces (dashboard, CLI, code), verified at the end. An example is a listing — the reader’s only action is copy and adapt. If the reader must do things outside the code for it to work, either fold them into a one-line assumptions note or write a how-to.
• Reference. Reference is complete and neutral, indexed by the product’s surface. Examples are selective and opinionated, indexed by the reader’s goal. The reference shows every field send() accepts; the example shows the three you use to batch.
• A tutorial. No narrative, no teaching, no parts. An example assumes competence and gets out of the way.

The two laws of the type:

1. Complete and runnable. Full imports, full config, no elided lines — a fragment that “you’ll need to adapt” isn’t an example, it’s homework. Copy-paste must produce the result the page shows.
2. Tested. Example code that doesn’t run is worse than none — it fails in the reader’s editor with the product’s name on it. Run them in CI if you can; stamp lastVerified either way.

Title & description

• Title: the goal plus the stack. “Verify signatures in a Next.js route handler” · “Debounce webhook bursts with Redis.” The stack qualifier is the type’s title signal — a how-to states a surface-neutral goal (“Rotate a signing secret”); an example names the environment its code lives in, because the code is the content. (A deliberate softening of the how-to title grammar: the imperative verb matches how-to; the stack suffix disambiguates.) Never “Example 3” or “Miscellaneous snippets.”
• Description formula: “What the code does, in the stack it’s written for.” — e.g. “Verify Hookline signatures in a Next.js route handler, rejecting replays.”

Scaffold this page

Install the recipe — your coding agent reads the full skeleton and checklist and adapts them to your product:

npx @cloudflare/nimbus-docs add content-example

yarn dlx @cloudflare/nimbus-docs add content-example

pnpm dlx @cloudflare/nimbus-docs add content-example

bunx @cloudflare/nimbus-docs add content-example

The cookbook form. Several related examples can share one page: the page takes a noun-phrase category title (“Signature verification,” “Batching”), and each ## entry follows the single-page skeleton the scaffold installs, minus the frontmatter — goal line, assumptions line, code, shown result, How-it-works. One lastVerified for the page means its oldest-verified entry. Split an entry to its own page when its code outgrows a screen. Adding a related example goes on the category page first; a new page needs a new category or an outgrown entry.

Component guidance

• Titled code blocks (title="app/api/hooks/route.ts") are the signature component — the filename is load-bearing context. Code groups for a multi-file example; one file is better when honest.
• Comments inside the code carry point-of-use notes (// rejects deliveries signed >5 min ago) — the one place where code comments beat prose, because they survive the copy-paste.
• Doesn’t fit: Steps (nothing is performed), Cards, Accordions (hidden code is unfindable and unextractable), Tabs for languages unless every tab is maintained and tested — an untested tab is a broken example hiding behind a tested one.

Ending

Shown result → How it works (when needed) → See also. No verify section (the how-to’s move — here the shown result and the tests carry that weight), no next-steps journey (the reader came for the code and is leaving with it).

Thresholds

• One goal per example. The title test: if it needs “and,” split it.
• Explanation must not outgrow the code. When How-it-works starts needing paragraphs instead of bullets, a concept or how-to is trying to get out — link it instead.
• Handle the errors the pattern is about; let the rest throw. State the error convention up front so entries don’t oscillate between a bare happy path and production hardening. Hedging code the goal doesn’t need is prose in disguise.
• Cookbook pages: same internal template per entry, goal-indexed, most-wanted first.

Links & freshness

Link the concept behind the pattern and the reference for every magic value; link from the related how-to back to the example (“just want the code? →”). Freshness is the type’s whole reputation: examples are tested artifacts, re-run on every release that touches their APIs (CI if possible), lastVerified stamped — a cookbook of code that no longer compiles is the loudest possible signal a product is unmaintained.

Agent notes

• Agents lift examples verbatim, so completeness is correctness: an elided import becomes a hallucinated import in someone’s codebase; a ... in the code becomes anything at all.
• State assumptions as checkable facts on the page (versions, env vars) — the agent can’t infer them from a rendered screenshot of your project.
• Realistic values throughout; placeholders only in <angle-brackets> and only where a real value can’t exist.
• The How-it-works bullets are retrieval gold: they pair the non-obvious line with its reason in one chunk, which is exactly what stops an agent from “simplifying” the load-bearing part (req.text() → req.json()). Flag any bullet that rests on provider-specific behavior explicitly, so an adapting agent knows what to re-check.

Checklist

Advisory — self-review for author or agent, never a build gate:

• Title is the goal plus the stack (cookbook page: noun-phrase category); one goal
• Assumptions stated in one line as checkable facts (versions, env)
• Code complete and runnable as pasted — full imports, zero elisions, type-checks under strict settings
• Shown result present: the output the pasted code produces, and how to elicit it
• Realistic values; placeholders only in <angle-brackets>
• How-it-works covers only the non-obvious lines; provider-specific assumptions flagged
• Error handling scoped to what the pattern is about
• Variations are links, not bolted-on listings; cookbook entries share one internal template
• Tested against the current release (CI if possible); lastVerified stamped (cookbook: oldest entry)