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

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)