Concept Guide Template

Concept guides establish a shared mental model before feature or API docs. Define the idea, show how it behaves over time, and point to practical follow-ups.

❌ DO NOT COPY — Guidance & Constraints

Frontmatter must include title, description, icon. Lead with a definition + analogy in two sentences max.
Add an <Info> block (“Why it matters”) with 2–3 bullets summarizing user impact. Use <Warning> near limitations or beta callouts.
Introduce vocabulary via ## Key terms (table or bullets) before diving deeper.
When migrating legacy pages, preserve canonical distinctions (e.g., short-term vs long-term) and fold them into the template rather than replacing them with new frameworks.
Organize the body with question-style headings (How does it work?, When should you use it?, How it compares). Optional diagrams should be left-to-right (graph LR).
Include at least one light code/JSON snippet or data table so the concept ties back to implementation.
Close with a “Put it into practice” checklist, “See it live” links, and the standard two-card CTA (left = feature/reference, right = applied cookbook).

✅ COPY THIS — Content Skeleton

mdx

---
title: [Concept name]
description: [One-sentence promise of understanding]
icon: "lightbulb"
---

# [Concept headline]

[Define the concept in one sentence.] [Add an analogy or context hook.]

<Info>
  **Why it matters**
  - [Impact bullet]
  - [Impact bullet]
  - [Impact bullet]
</Info>

## Key terms

- **[Term]** – [Short definition]
- **[Term]** – [Short definition]
```mermaid
graph LR
  A[Input] */} B[Concept]
  B */} C[Outcome]
```

## How does it work?

[Explain lifecycle or architecture.]

```python
# Minimal snippet that anchors the concept in code
```

<Tip>
  [Nuance or best practice related to this concept.]
</Tip>

## When should you use it?

- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

## How it compares

| Option | Best for | Trade-offs |
| --- | --- | --- |
| [Concept] | [Use case] | [Caveat] |
| [Alternative] | [Use case] | [Caveat] |

<Warning>
  [Optional limitation or beta note.] Delete if not needed.
</Warning>

## Put it into practice

- [Operation or feature doc that relies on this concept]
- [Another supporting doc]

## See it live

- [Cookbook or integration demonstrating the concept]
- [Recording, demo, or sample repo]

<CardGroup cols={2}>
  <Card
    title="[Feature or reference]"
    description="[Why this deep dive matters]"
    icon="book"
    href="/[feature-link]"
  />
  <Card
    title="[Applied cookbook]"
    description="[What they’ll build next]"
    icon="rocket"
    href="/[cookbook-link]"
  />
</CardGroup>

✅ Publish Checklist

Definition + analogy stay within two sentences.
“Why it matters” bullets focus on user impact, not implementation detail.
Key terms, lifecycle explanation, and comparison table are present (or intentionally removed when irrelevant).
At least one code/JSON/table example grounds the concept.
CTA pair links to a feature/reference (left) and applied tutorial (right).

Browse Other Templates