Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# recipe Card

# Recipe Cards

Recipes live in `_content/recipes/`. Organize with subdirectories only if
the user wants that — don't impose a taxonomy.

## Frontmatter

- `title:` — required. Recipe name.
- `description:` — optional prose.
- `source:` — optional. Where the recipe came from, as an object with at
  least one of: `label` (a freeform name — a cookbook, a person),
  `href` (an external URL), or `ref` (a card, e.g. a frozen
  `*.webpage.card`). E.g. `source: {label: "The Kitchen"}` or
  `source: {href: "<the recipe's URL>"}`.
- `tags:` — optional array of strings.
- `hero-image:` — optional representative image, as an object with
  exactly one of `ref` (into this card's attach scope, e.g.
  `{ref: "attach/finished.jpg"}`) or `href` (an external URL).

## Body

Markdoc-annotated markdown. Vocabulary:

- `{% yield amount="4" %}4 servings{% /yield %}` — the scaling base.
  `amount` is the number the recipe view multiplies against when
  scaling; the body text is human-readable.
- `{% ingredient amount="2" unit="cups" %}all-purpose flour{% /ingredient %}`
  — inline (within a step's prose) or block (typically inside a list
  item). The frontend recipe view scales the `amount` attribute
  using a `Fraction` parser, so values like `1/4`, `1 1/2`,
  `2-3` (range) all work.
- `{% step %}First, do this thing.{% /step %}` — one step of the
  recipe. Numbered automatically by the recipe view (CSS counter).
- `{% substitution for="buttermilk" %}Use milk + 1 tbsp lemon
  juice.{% /substitution %}` — a substitution. `for` names the
  ingredient or step being substituted.
- `{% subrecipe ref="/_content/recipes/sauces/Marinara.recipe.card" %}
  Make a half batch.{% /subrecipe %}` — link to a sibling recipe.
  `ref` is a card path — see PROVENANCE for ref semantics.
- `{% recipe-section name="Sauce" %}` — block. Groups a sub-recipe
  within a recipe (e.g. sauce + pasta in one card). Optional.

Free-form markdown headings (`## Notes`, `## Equipment`) work
alongside the tags for sections that don't need structure.

## Fidelity

When you structure a recipe from something the user wrote or saved, keep
their measurements and wording exactly as given: `unit="tbsp"` and body
text "1 tbsp", never "1 T"; "1/2 cup" stays "1/2 cup", not "½ c".
Abbreviating units silently is a real cooking hazard ("1 T" vs "1 t" is a
3× error), and any silent edit to their quantities undermines trust in the
whole card. Convert or normalize only when asked, and say that you did.

## File naming

`_content/recipes/Recipe_Name.recipe.card`

## The `contains:` field

Give this card a one-sentence `contains:` — the prime retrieval field for
`bbx search` and listings. How to write a good one (carry the information when
it's concise, never a list of parts, under 200 characters) is in the agent
guide's ABOUT_CARDS section.

## Templates

### recipe

A recipe card with ingredients, steps, and scaling support

```bash
bbx create <path>.recipe.card -t recipe
```

Template: recipe
Description: A recipe card with ingredients, steps, and scaling support
Card types: recipe

Arguments:
  title: Recipe name
  description (optional): What the dish is
  servings (optional): Number of servings (default: 4)