---
title: "Example"
description: "The recipe for cookbook pages — complete, runnable code showing how something is done, with prose only for the non-obvious. Checklist and a scaffold command."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.klounge.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Example

> **Need**
>
> At work, acting — the reader wants working code to copy and adapt. Their opening question: *"Show me working code for X."* Not a procedure to follow (how-to), not a lesson (tutorial): code showing how something is *done*, which is a different thing from instructions for doing it — the copyable-code half of the documentation gap. In the agent era this is the highest-leverage type: both reader personas start at the code sample, and agents paste examples into codebases verbatim.

## 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:

```sh
npx add content-example
pnpm dlx add content-example
yarn dlx add content-example
bunx 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)

Source: https://docs.klounge.kr/writing/recipes/example/index.mdx