---
title: "Write a concept page"
description: "The recipe for understanding pages — what a thing is, why it works that way, and where its boundaries are. No steps, no instructions. Checklist and a scaffold command."
---

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

# Write a concept page

> **Need**
>
> At study, reflecting — the reader can already operate the product, or is about to, and wants the mental model: what this thing *is*, why it's designed this way, when to reach for it. Their opening question: *"What is X, really?"*
>
> This is the most neglected type, and the one where hand-written quality matters most: reference and procedures are increasingly read by machines, while mental models stay the human layer.

## When to use it

Write a concept page when readers keep needing the same explanation in the middle of other pages — that's the signal the model deserves its own home. It is not:

- **A how-to.** The hard boundary is **no procedural steps, no configuration walkthroughs**. Illustrative code is welcome when it shows the idea rather than asking the reader to follow along. The test for a borderline snippet: if removing it loses an example, it was illustrative; if removing it loses the instructions, it was a walkthrough.
- **Reference.** Reference is complete and neutral; a concept is selective and opinionated. A concept page should take positions — this is the one type where "we recommend" and design rationale belong.
- **An overview.** The overview routes; the concept explains. If most of the page is links, it's an overview wearing the wrong title.

One concept per page. "Delivery and signing" is two pages with a link between them.

## Title & description

- **Title: a concise noun phrase naming the concept.** "Delivery guarantees." "Webhook signing." Avoid "Overview," "Introduction," and "How it works" because they name the genre instead of the subject and collide with every other page titled the same way. Self-check: a good concept title still reads naturally with "About" in front of it ("About delivery guarantees" ✓).
- **Description formula:** "*What the concept is* and *what it means for the reader's code or choices*." — e.g. "What Hookline guarantees about delivery — and what your endpoint must still handle itself."

## Scaffold this page

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

```sh
npx @cloudflare/nimbus-docs add content-concept
yarn nimbus-docs add content-concept
pnpm nimbus-docs add content-concept
bunx @cloudflare/nimbus-docs add content-concept
```

## Component guidance

- **Prose is the primary component.** Short paragraphs, one idea per section — this is the type where writing quality carries the page.
- **Diagrams and illustrative code/payloads** fit when they show the model; always with a text equivalent for the diagram.
- **Comparison tables** fit in Boundaries when there's a genuine either/or.
- **Doesn't fit:** Steps (the defining ban), Tabs (a concept doesn't vary by platform — if it does, it's two concepts), Cards.

## Ending

**Boundaries → See also.** Ending on scope is what most defines this type. Stating what the concept is *not*, next to its confusable neighbors, is the cheapest way to make the model stick.

## Thresholds

- **A shallow-but-correct model by the end of paragraph two.** If the reader must finish the page to avoid a *wrong* model, the opening is misordered.
- **≤ ~1,500 words** as a practical limit. Pages in an explicitly ordered core-concepts sequence meant to be read start-to-finish are exempt. A *standalone* concept that outgrows the cap splits into two concepts.
- **At least one sentence of design rationale.** A concept page with no "why" is a glossary entry stretched to a page.

## Links & freshness

Concept pages are hubs: link every how-to that applies the model and the reference that lists it, and link *back* from those pages, so the model is explained once.

Concepts rot slowest, but re-read them when the design changes; a "why" that no longer matches the product misleads. `lastVerified` is optional here, since the trigger is design change, not the calendar.

## Agent notes

- The definition paragraphs are what agents retrieve and quote when asked "what does X guarantee" — they must be self-contained and unambiguous alone, without the sections below.
- State the contract in checkable terms ("at least once," "per-endpoint," "not ordered") rather than reassuring ones ("reliable," "robust") — agents propagate vague adjectives into wrong code.
- Boundaries double as the agent's negative knowledge — what *not* to assume. Write them as flat declarative bullets.

## Checklist

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

- [ ] Title is a noun phrase; not "Overview" / "Introduction" / "How it works"; passes the "About X" read-aloud test
- [ ] Definition first; correct shallow model by paragraph two
- [ ] Design rationale present — product tradeoff, or domain constraint + product stance
- [ ] Zero procedural steps or config walkthroughs; code passes the illustrative test
- [ ] Boundaries section: what it's not + confusable neighbors
- [ ] Diagram (if any) has a text equivalent
- [ ] Ends with See also linking the how-tos and reference that depend on this model
- [ ] ≤ ~1,500 words standalone (course-sequence pages exempt); one concept

Source: https://nimbus-docs.com/style-guide/concept/index.mdx