Concept template

When to use

• Shelf: learn/concepts/<topic>/
• kind: concept
• Diátaxis mode: explanation (one idea per page)
• Readers served: quick mental-model lookup; agents disambiguating terms before authoring

Shorter than a handbook chapter — one concept, one page.

Design rationale

• One-sentence definition first — explanation docs must be repeatable by beginners (Diátaxis explanation).
• Why before how — motivation prevents rote memorization (inverted pyramid for technical concepts).
• How it works needs diagram for non-trivial flows — warrant test (visuals gate).
• When to use / avoid as paired sections — explicit boundaries reduce misuse (API design — document anti-patterns).
• Related links, not sequential next — concepts are non-linear (handbook/guide linking pattern).

Copy-paste skeleton

---
title: "Concept name"
description: One sentence definition a beginner can repeat back.
sidebar:
  label: "Concept name"
  order: N
category: <topic>
kind: concept
status: current
tags: [concept, topic]
---

**&lt;Concept&gt;** is &lt;one plain sentence&gt;.

## Why it exists

The problem it solves — 2–4 sentences.

## How it works

\`\`\`mermaid
flowchart LR
  A["Input"] --> B["Process"] --> C["Outcome"]
\`\`\`

Numbered walkthrough if helpful (keep steps short).

## When to use it

- ✅ &lt;good fit&gt;

## When to avoid it

- ❌ &lt;anti-pattern&gt;

:::tip[Related]
[Handbook](/tech-stack/laravel/codecanyon/learn/handbooks/) · [Guide](/tech-stack/laravel/codecanyon/learn/guides/)
:::

Anti-patterns

• Do not turn concept pages into playbooks — link to Build for procedures.
• Do not skip diagram on multi-part processes.
• Do not use emoji-only bullets without prose context on public pages (prefer - lists + short lead-in).

Worked example

• Content architecture — definitional opening, Learn vs Build, type lookup tables, Mermaid

Sources

• Diátaxis — Explanation — single-idea concept pages.
• Google developer documentation style guide — Definitions — crisp definitional openings.
• Diátaxis — Overview — concept vs guide vs handbook depth.
• Doc components — warrant test — diagram triggers.
• Writing style → Doc-type spines