docs/templates/cookbook_template.mdx
Cookbooks are narrative tutorials. They start with a real problem, show the broken path, then layer production-ready fixes. Use this template verbatim so every contributor (human or LLM) ships the same experience.
user_123.Paste the block below into a new cookbook, then replace all placeholders. Remove any section you don't need only after the happy path works.
---
title: [Cookbook title: action oriented]
description: [1 sentence outcome]
---
# [Hero headline]
[Two sentences max: state the user's pain and what this cookbook will fix.]
<Tip>
[Only include if you truly have launch news. Delete otherwise to keep the intro crisp.]
</Tip>
<Info icon="clock">
**Time to complete:** [~X minutes] · **Languages:** Python, TypeScript
</Info>
## Setup
```python
default_language = "python" # replace with real imports
```
```typescript
// Equivalent TypeScript setup goes here
```
<Note>
Mention any prerequisites (API keys, environment variables) right here if the reader must do something before running code.
</Note>
## Make It Work Once
[Set context with characters + goal.]
```python
# Happy-path example
```
```typescript
// Happy-path example (TypeScript)
```
<Info icon="check">
Expected output (Python): `[describe inline]` · Expected output (TypeScript): `[describe inline]`
</Info>
## The Problem
[Explain what breaks without tuning.]
```python
# Broken behaviour
```
```typescript
// Broken behaviour
```
**Output:**
```
[Paste noisy output]
```
[One sentence on why the result is unacceptable.]
## Fix It: [Solution Name]
[Explain the fix and why it helps.]
```python
# Improved implementation
```
```typescript
// Improved implementation
```
**Retest:**
```python
# Same test as before
```
```typescript
// Same test as before
```
**Output:**
```
[Cleaner result]
```
[Highlight the improvement + remaining gap if any.]
## Build On It: [Second Layer]
[Add another enhancement, e.g., metadata filters, rerankers, batching.]
```python
# Additional refinement
```
```typescript
// Additional refinement
```
<Warning>
Call out the most common mistake or edge case for this layer.
</Warning>
## Production Patterns
- **[Pattern 1]**: `[When to use it]`
```python
# Example snippet
```
```typescript
// Example snippet
```
- **[Pattern 2]**: `[When to use it]`
```python
# Example snippet
```
```typescript
// Example snippet
```
## What You Built
- **[Capability 1]**: [How the cookbook delivers it]
- **[Capability 2]**: [How the cookbook delivers it]
- **[Capability 3]**: [How the cookbook delivers it]
## Production Checklist
- [Actionable step #1]
- [Actionable step #2]
- [Actionable step #3]
## Next Steps
<CardGroup cols={2}>
<Card
title="[Related cookbook / deep dive]"
description="[Why this pairs well with the current guide]"
icon="arrow-right"
href="#related-link"
/>
<Card
title="[Next cookbook in journey]"
description="[Set expectation for the next step]"
icon="rocket"
href="#next-link"
/>
</CardGroup>
[placeholder] and remove unused sections.<Note> stating language limitation).<Info icon="check"> or inline equivalent.<CardGroup cols={2}>.Stick to the skeleton above. If you need to deviate, document the rationale in the PR so we can update the template for everyone else.