Recipe markdown for agents

The recipe markdown that agent access and the command-line tool read and write: what recipes.get returns as markdown, and what recipes.create, recipes.update and recipes.validate take as markdown. It isn’t the recipe text that Copy recipe writes, and the Add Recipe sheet doesn’t read it this way.

A complete example

# Pancakes

Fluffy weekend pancakes.

Category: Breakfast
Tags: quick, weekend
Makes: 12 pancakes
Serves: 4
Time: 25 min
Active: 15 min
Source: [NYT Cooking](https://cooking.nytimes.com/…)

## Mix the batter.

- Flour (all-purpose), 190 g
- Milk, 240 g; or Buttermilk, 240 g
- Butter, 2 tbsp: Melted.

Whisk the dry ingredients. Add the wet ones and stir until just combined.

## Make the syrup.

> @[Maple Syrup], 2: Make a double batch.

---

Try adding blueberries to the batter.

Lines

Line	Shape	Rules
Title	`# Pancakes`	The first line that isn’t blank. Required, and can’t be blank
Description	Prose after the title	Paragraphs and front-matter lines can come in any order before the first step
Front matter	`Key: value`	The keys below, capitalized, at the start of the line, with a space after the colon
Step	`## Mix the batter.`	Starts a titled step. The title can’t be blank
Ingredient	`- Name, quantity: prep note`	One per line, under its step
Cross-reference	`> @[Recipe Title], multiplier: note`	A step of its own
Instructions	Prose inside a step	Markdown
Footer	Everything after the first `---` line	Markdown. Bullets here are text, not ingredients

Front matter

Key	Example	Rules
`Category:`	`Category: Breakfast`	Up to 50 characters
`Tags:`	`Tags: quick, slow cooker`	Comma-separated. Each tag is lowercased, and spaces become hyphens (`slow-cooker`)
`Makes:`	`Makes: 12-16 pancakes`	Starts with a number and needs a noun after it; `Makes: 12` is refused
`Serves:`	`Serves: 4-6`	A positive whole number or a range. `4-6`, `4–6` and `4 to 6` all work; a range reads low to high and needs two different numbers
`Time:`	`Time: 1 hour 30 min`	Weeks, days, hours and minutes, alone or combined (`1h 30m` works). A bare number is minutes
`Active:`	`Active: 15 min`	Same units as `Time:`. Needs `Time:`, and can’t be longer than it
`Source:`	`Source: [NYT Cooking](https://…)`	A Markdown link, a bare `http://` or `https://` address, or a name alone. Up to 500 characters
`Adapted:`	`Adapted: yes`	`yes` is the only value; it marks the source as adapted. Any other value stays description text

A front-matter line written slightly wrong near the top, such as serves: 4 or Serves:4, is refused with a hint rather than kept as description. Further down the recipe, a line that looks like front matter is ordinary prose.

Ingredients

- Name, quantity: prep note. The first comma ends the name and the first colon starts the prep note; a comma inside parentheses doesn’t count, so - Sugar (brown, packed), 150 g keeps its whole name. The quantity and the prep note are optional: - Butter is a name alone, and - Onion: diced is a name with a prep note. - Onion, diced puts diced in the quantity.

A quantity can carry a second measure in parentheses (- Sugar, 2 cups (250 g)), and a package is its count and kind, a comma, then one package’s size and each (- Tomatoes, 2 cans, 14.5 oz each). A line that leads with its amount instead, such as - 1 cup sugar, is read when Mirepoix can tell the amount from the name.

Substitutes and the optional mark go before the colon, as ; or and ; optional tails:

- Milk, 240 g; or Buttermilk, 240 g
- Basil (fresh), 1/4 cup; optional: Torn.
- Butter, 2 tbsp; or Olive oil, 2 tbsp; optional

Each ; or takes Name, quantity, with the quantity optional, and a line takes up to eight. ; optional comes last. A prep note after the colon belongs to the whole line; a substitute’s own prep note can’t be written here. Anything else after a ; before the colon is refused.

Cross-references

> @[Recipe Title] embeds another recipe. A multiplier follows a comma (2, 1/2 or 1.5), and a note follows a colon:

## Make the syrup.

> @[Maple Syrup], 2: Make a double batch.

A cross-reference stands alone in its step: one per step, with no ingredients or instructions beside it. It sits under a ## step, or leads the recipe above its ingredients, instructions and first ## line, where each becomes an untitled step of its own. Anywhere else it’s refused. Writing the multiplier first (> 2x @[Maple Syrup]) is the old form and is refused.

In instructions, a prep note or the footer, @[Recipe Title] is a link to that recipe, and a * after a number makes it scale.

Steps

When a recipe uses ## steps, every ingredient must sit under one; an ingredient above the first ## is refused. A recipe with no ## lines is one untitled step.

What this markdown can’t spell

It has no way to spell a step that mixes a cross-reference with its own ingredients, two cross-references in one step, an untitled step after a titled one, or a substitute’s own prep note. When a recipe holds one of these, a read says so (markdown_round_trips is false). Send the editor’s form, structure, instead — see Adding and changing recipes.