Copy this template when creating a new conceptual page. Replace all placeholder text in [brackets]. Remove sections that don’t apply.
[Opening paragraph: what this concept is and why it matters. Answer the question a developer would ask before clicking on this page.]
[Optional second paragraph: the key insight about this concept that prevents common mistakes. If you have a “this is the most important thing to understand” statement, put it here rather than in a callout box.]
[Explain the mechanism. Use plain language. If an analogy helps, use it — but be careful that it doesn’t fall apart under scrutiny.]
[Include a diagram if the concept has a flow, hierarchy, or sequence that’s hard to describe in prose:]
[ASCII diagram or Mermaid code block]
[Continue explanation. If there are sub-components or variations, introduce them here as H3 sections.]
[Explanation.]
[Important behaviors that affect how the user writes code or configures the system. These are the things that cause bugs if the user doesn’t know them.]
[What this concept doesn’t support. What edge cases exist. This is not an apology — it’s useful technical information that saves users time they’d otherwise spend testing the limits themselves.]
[A short, concrete example that shows the concept in action. Enough code or configuration to illustrate the point — not a full tutorial.]
[Example]
[Annotate the key parts of the example that illustrate the concept.]