Skip to main content

​
Cookbook Template

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.

​
❌ DO NOT COPY — Guidance & Constraints

  • Tell a story: problem → broken demo → iterative fixes → production patterns.
  • Keep tone conversational; use real names (“Max”, “Sarah”), not user_123.
  • Opening must stay tight: ≤2 short paragraphs (no bullet lists) before the first section.
  • Inline expected outputs immediately after each code block.
  • When modernizing an existing cookbook, keep the narrative beats, screenshots, and sample outputs—reshape them into this arc instead of rewriting unless the workflow changed.
  • Limit callouts to 3–5 per page. Prefer narrative text over stacked boxes.
  • Always provide Python and TypeScript tabs when an SDK exists for both.
  • Every page must end with exactly two navigation cards (left = related/side quest, right = next cookbook in the journey).

​
✅ COPY THIS — Content Skeleton

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

// Equivalent TypeScript setup goes here
Mention any prerequisites (API keys, environment variables) right here if the reader must do something before running code.

​
Make It Work Once

[Set context with characters + goal.] 
# Happy-path example

// Happy-path example (TypeScript)
Expected output (Python): [describe inline] · Expected output (TypeScript): [describe inline]

​
The Problem

[Explain what breaks without tuning.] 
# Broken behaviour

// 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.] 
# Improved implementation

// Improved implementation
Retest: 
# Same test as before

// 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.] 
# Additional refinement

// Additional refinement
Call out the most common mistake or edge case for this layer.

​
Production Patterns

  • [Pattern 1] — [When to use it] 
    # Example snippet

    // Example snippet
  • [Pattern 2] — [When to use it] 
    # Example snippet

    // 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

[Related cookbook / deep dive]

[Next cookbook in journey]


---

## ✅ Publish Checklist (Keep Handy)
- [ ] Replace every `[placeholder]` and remove unused sections.
- [ ] Python & TypeScript code compile (or TypeScript omitted with explicit `<Note>` stating language limitation).
- [ ] Each code block is followed by output + `<Info icon="check">` or inline equivalent.
- [ ] Callouts ≤ 5 total; no emoji, only Mintlify icons.
- [ ] Exactly two cards in the final `<CardGroup cols={2}>`.
- [ ] Added verification narrative (what success looks like) in every major step.
- [ ] Linked related docs (cookbooks, guides, reference) in Next Steps.

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.

​
Browse Other Templates

Quickstart

Operation Guide

Feature Guide

Concept Guide

Integration Guide

Cookbook

API Reference

Parameters Reference

Migration Guide

Release Notes

Troubleshooting Playbook

Section Overview

Contribution Hub

Docs Home