Recipe format

Recipes read as plain text. An export writes a readable .md file per recipe in the format below, Copy as text on a recipe page puts the same shape on your clipboard, and an import reads it back. You never type this format in the app — every recipe you add or change goes through the recipe editor, where the title, the amount, the prep note, and each substitute have their own box.

This text is a rendering of the recipe, not the recipe itself. An export puts the exact record beside it, as a .json file in the archive’s recipes/ folder, and that’s what an import reads — so the few shapes this format can’t spell (named at the end of this page) survive an export and come back intact.

So this page is the shape of the text, not a set of instructions for writing a recipe by hand. Read it to edit an exported file offline, to hand a recipe to another program, or to see what a paste will turn into. Paste a whole recipe into the title box of a blank new recipe and Mirepoix reads it with the rules below; text it can’t read as a recipe is offered to Mirabel to import instead.

A complete example

# Pancakes

Fluffy weekend pancakes.

Category: Breakfast
Tags: quick, weekend
Makes: 12 pancakes
Serves: 4
Time: 25 min
Active: 15 min

## Mix the batter.

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

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

## Cook the pancakes.

- Butter
- Blueberries, 1 cup; optional

Pour about 60 g of batter per pancake onto a hot buttered pan.
Cook until bubbles form and edges look set. Flip and cook 1 minute more.

---

Try adding blueberries or chocolate chips to the batter.

Title

The first non-blank line, marked with #. Required. It’s the editor’s Recipe title box.

# Pancakes

Description

The editor’s description, written between the title and the first step. Description and front matter can appear in any order — a Serves: line can sit above the description, below it, or between its paragraphs. (In a recipe with no ## headers, prose before the first ingredient line counts as the description; prose after it becomes the step instructions.)

# Pancakes

Fluffy weekend pancakes.

Front matter

The editor’s Serves, Makes, Time, Active, Category, Tags, and Source fields, written as lines before the first step. Each line is one key, a colon, at least one space, and a value — no leading whitespace. A field you left empty gets no line.

Makes: and Serves: can appear together — Makes: 1 loaf paired with Serves: 12 is valid.

Both Makes: and Serves: also take a range — a hyphen, an en dash, or the word “to” all work: Serves: 4-6, Serves: 4–6, and Serves: 4 to 6 all mean the same thing, and the same three spellings work for Makes: 12-16 cookies. A range always reads low to high; Serves: 6-4 is rejected with a hint to swap it. Serves: 4-4 is rejected too, since a range needs two different numbers — write Serves: 4 instead. Makes: treats equal endpoints differently: Makes: 12-12 cookies isn’t rejected, it just counts as the single value Makes: 12 cookies. A range displays on the recipe page with an en dash (Serves 4–6, Makes 12–16 cookies), and both ends scale together when you scale the recipe.

Makes: also understands dozens. Any number before dozen — whole, decimal, mixed, or a word like one or two — multiplies by 12: Makes: 1 dozen scones counts as 12 scones, Makes: 2 dozen cookies as 24, Makes: 1 1/2 dozen eggs as 18, and Makes: one dozen as 12. A dozen range works too — Makes: 1 1/2-2 dozen rolls counts as 18-24 rolls. Leave off the noun and it counts items — Makes: 1 dozen means 12 items. Makes: half dozen isn’t recognized.

A duration displays back in the largest tidy unit. An exact whole number of weeks shows as weeks (14 days reads as 2 weeks); anything else shows in days, hours, and minutes (15 days stays 15 days). Weeks are the longest unit — months and years aren’t accepted, since their length varies.

Source

Source: takes exactly one of three shapes:

Source: [NYT Cooking](https://cooking.nytimes.com/…)   ← a name and an address
Source: https://cooking.nytimes.com/…                  ← an address alone
Source: Grandma's index card                           ← a name alone

It renders in two places. A byline sits just under the title and description — From followed by the name. At the bottom of the page, above the footer text, a sentence reads Read the original recipe from the name, with the original recipe as the link. Both links open in a new tab. When the recipe has a name and no address, both surfaces are plain text — From Grandma's index card at the top, From Grandma's index card. at the bottom. When it has an address alone, both surfaces use the site’s host as the name. A link address must start with http:// or https://; any other scheme is rejected.

Anything between the three shapes is rejected on the way in rather than filed away as a name — an address buried in a name (Source: NYT — https://cooking.nytimes.com/…) or a Markdown link broken by a typo. Write one of the three shapes and the error goes away. Import a recipe from a link and Mirepoix fills the two Source fields in for you, using the site’s address as the link and its host as the name.

Steps

Each step starts with a ## heading, and the heading text is the step’s title from the editor. Periods at the end (## Mix the batter.) are convention in the sample recipes, not a parser requirement.

## Mix the batter.

- Flour, 190 g
- Milk, 240 g

Whisk until smooth.

A recipe with ingredients but no ## headings is still valid — the whole body is read as a single implicit step. That’s the only untitled step this text form can spell: reading a recipe back in, an ingredient or paragraph with no ## above it always joins the step before it, rather than starting a fresh one of its own.

The editor isn’t limited to that. Leaving a step’s title box blank there marks a deliberate, unnamed step break — wherever you put it, not just at the start — and typing an ingredient right after a paragraph starts one automatically. Both are legal to save, but this text form can’t spell any of it, and what a plain paste or an import does with it on the way back in depends on where the break sits. Put an unnamed step after a titled one and it folds into whatever came right before it in the text — the content survives, but the step break it marked doesn’t. Put one before the first heading instead and the outcome is worse: prose there is swept into the description rather than kept as a step, and an ingredient bullet there is rejected outright once the recipe uses any ## heading at all — the whole file fails to come back, not just the step break.

Automatic Celsius conversion

When a step, prep note, or the footer names a temperature in Fahrenheit — 350°F, 350 F, 350F, 350 deg F, 350 degrees F, 350 Fahrenheit, any capitalization — the app appends a computed Celsius equivalent, so Preheat oven to 350°F reads as Preheat oven to 350°F (~175 °C). A range converts as a range: 350-375°F becomes 350-375°F (~175–190 °C). The leading ~ marks it as an estimate, the same convention as the automatic metric weight below — the app never changes the temperature the recipe states.

The conversion is skipped when the same paragraph already spells out an explicit Celsius temperature — 350°F (175°C), 180 C/350 F, 350 degrees F (175 degrees C) — so an already-converted recipe never ends up with two. A bare 350° with no F or C letter is left alone; the app only converts a temperature that says which scale it’s in.

Ingredients

Ingredient lines start with - . The shape is:

- Name, quantity: prep note

• Name — matched against the ingredient catalog for grocery tracking
• Quantity — optional. Numbers, units (any capitalization), ranges, fractions, or unicode glyphs
• Prep note — optional. Renders in smaller text below the line

Those three are the editor’s three boxes on an ingredient row, written out on one line with a comma and a colon between them.

Examples:

- Butter                          ← name only
- Flour (all-purpose), 190 g      ← name and quantity
- Eggs, 2                         ← name and count
- Eggs, 6 large                   ← count with a size word
- Eggs, 1-2                       ← name and range
- Milk, ½ cup                     ← unicode fraction
- Chickpeas, 1 can (15 oz)        ← alternate measure in parentheses
- Butter, 2 tbsp: Melted.         ← name, quantity, and prep note

Supported unicode fraction glyphs: ½ ⅓ ⅔ ¼ ¾ ⅕ ⅖ ⅗ ⅘ ⅙ ⅚ ⅛ ⅜ ⅝ ⅞. Mixed forms like 1½, 1 1/2, or the hyphenated 1-1/2 work too. Ranges accept -, –, —, or − between numbers, and must read low to high. A backwards range like 3-2 is rejected with a hint to swap it. When you scale the recipe, both ends of a range scale — 1-2 at 2× becomes 2-4.

Units are flexible about how you write them. Capitalization doesn’t matter — 45 mL, 15 OZ, and 5 Tbsp all work. Common shorthand is understood: T for tablespoon and t for teaspoon (case tells them apart), c for cup, and # for pound. An abbreviation may carry a trailing period (15 oz., 2 tsp., fl. oz.), and British spellings work — litre, millilitre, gramme, kilogramme, and their families. Even gō, the Japanese rice measure, is recognized — with or without the macron, so plain go works too. A few near-misses aren’t accepted: tbs, tbl, and floz.

A quantity can carry a second, equivalent measure in parentheses at the end. Inside goes a clean number followed by one of three things: a unit (2 cups (250 g), 1 can (360 mL)), a portion word (1 cup (2 sticks), 1 box (2 packets)), or nothing at all — a bare count (100 g (2)). Units follow the same flexible spelling rules, so 1 can (360 mL) works. Both measures show together and scale as a pair — 1 cup (2 sticks) at 2× becomes 2 cups (4 sticks), and 2 cups (250 g) at 2× becomes 4 cups (500 g) (scaled text renders the standard lowercase abbreviation; the exact spelling shows at 1×). A range works on either side and scales on both ends — 2-3 tbsp (30-45 mL) grows at both the 2-3 and the 30-45 when you scale. Anything that isn’t a clean number plus a unit, portion, or count, like (about 15 oz), (8 oz each), or (16 Tbsp; 226 g), stays in the quantity as plain text and doesn’t scale.

A quantity with no number in it behaves the same way. Mirepoix keeps it as written, on any ingredient, and it doesn’t scale. Salt, to taste and Active dry yeast, q.b. both read back as typed — q.b. is short for quanto basta: as much as it takes.

Automatic metric weight

When an amount is in a US measure — cups, tablespoons, teaspoons, fluid ounces, pints, quarts, gallons, ounces, or pounds — the app shows a metric weight in grams or kilograms after it, so Flour (all-purpose), 2 cups reads as 2 cups (~250 g). The weight is computed from the ingredient catalog, by density for volumes and directly for ounces and pounds, and it scales with the recipe. Dash and pinch are recognized units too, converted directly at standard culinary approximations (a dash ≈ 0.6 g, a pinch ≈ 0.3 g) rather than by density — in practice the estimate rarely shows, since a single dash or pinch falls under the 10 g floor below.

The same weight appears after a portion the catalog knows by name — a stick of butter, a slice of cheese, a can of beans:

- Butter, 1⅔ sticks       → 1⅔ sticks (~190 g)
- American cheese, 2 slices → 2 slices (~55 g)
- Beans (any canned), 1 can → 1 can (~440 g)

And it appears after a bare count of an ingredient the catalog can weigh — produce you buy by the piece, eggs:

- Onion, 1   → 1 (~150 g)
- Eggs, 2    → 2 (~100 g)

A size word — small, medium, large, or extra large — can sit in the quantity next to the count, and the weight follows the size:

- Onion, 1 large  → 1 large (~150 g)
- Eggs, 6 large   → 6 large (~300 g)

The app uses that size’s weight when the catalog lists one, and otherwise falls back to the ingredient’s per-item weight if it has one.

Like the US-measure case, these scale with the recipe — two sticks of butter weigh twice as much as one.

The leading ~ marks it as an estimate the app worked out. That’s the difference from the alternate measure above: when you write your own measure in parentheses, like 2 cups (250 g), it shows with no ~ — it’s your figure, not an estimate the app computed. So you can always bake in your own conversion.

The weight appears only when it’s useful. It’s left off an amount already in metric (like g, kg, or ml), an ingredient that isn’t in the catalog, a portion or count the catalog can’t weigh, and any amount under about 10 grams — a teaspoon of vanilla or a single leaf of arugula isn’t worth weighing. And if you’ve written your own measure in parentheses, that wins and no estimate is added.

In this text form the colon and comma are reserved delimiters. The first colon starts the prep note; everything before it is the name and quantity, split at the first comma. (A comma after the colon stays in the prep note.) A comma inside parentheses doesn’t count, so Sugar (brown, packed), 150 g keeps its full name. A prep note with no quantity needs a colon — a comma puts the word in the quantity slot instead:

- Onion: diced      ← prep note
- Onion, diced      ← "diced" becomes the quantity

That’s a rule about written lines only. In the recipe editor the name, the amount, and the prep note each have their own box, and a comma or colon typed in one of them is ordinary text.

When two recipes share an ingredient, the grocery list combines the quantities. Two recipes calling for Flour, 190 g add up to 380 g on one line.

A line that leads with the amount

A line doesn’t have to lead with the name and a comma. A line that leads with the amount instead — - 1 cup sugar, - 1 cup parsley, chopped — is read the same way when Mirepoix can tell the amount from the name: it pulls the amount out and files the ingredient normally. This applies to a recipe file you import and to a whole recipe you paste in, not to the boxes in the editor.

When Mirepoix can’t tell them apart with confidence, the line falls back to the ordinary rules above. A comma-less line like - 1 cup sugar is kept whole, exactly as written; a line with a comma splits there as usual, the words after the comma landing in the quantity slot. Either way it shows up in Review ingredients (Nutrition) flagged for attention, where Fix this line… is the way to sort it out.

The standard Name, quantity: prep note form is unaffected by any of this — it’s already unambiguous, so Mirepoix uses it as written and never runs it through this extra reading step.

Alternatives and optional ingredients

An ingredient’s substitutes and its optional mark ride at the end of its line, as ; or and ; optional tails.

- Buttermilk, 1/2 cup; or Milk, 1/2 cup             ← a substitute
- Basil (fresh), 1/4 cup; optional                  ← skippable
- Butter, 2 tbsp; or Olive oil, 2 tbsp; optional    ← both

Each ; or tail takes the same Name, quantity shape the line itself uses, and the quantity is optional. One line takes up to eight substitutes. A substitute carries a name and an amount and nothing else — the prep note belongs to the whole line, whichever ingredient you use, and goes after a colon at the end:

- Butter, 2 tbsp; or Olive oil, 2 tbsp: For the pan.

; optional marks the whole line — every version of it — as one you can skip. It has to come last, after any ; or tails.

In the editor these are two verbs rather than punctuation. Add a substitute in an ingredient row’s ⋮ menu adds an or line with its own ingredient and amount boxes; Optional in the same menu marks the line, and a quiet optional appears at the end of the row. See Adding & editing recipes for the row’s full set of controls.

A semicolon inside parentheses stays part of the name, the same protection a comma gets. Anything else after a semicolon is a parse error, with a hint to write or <ingredient>, <quantity> or optional. A line that leads with its amount doesn’t combine with these tails: on a line carrying ; or or ; optional, write Name, quantity on the line and on each substitute.

On the recipe page the line reads as written: the first ingredient, then its substitutes in a quieter parenthetical, lowercased.

Buttermilk, ½ cup (or milk, ½ cup)

A substitute’s amount scales with the recipe like the line’s own. A line marked ; optional carries an optional pill after its quantity.

Which version your kitchen actually shops for is a separate choice you make on Groceries or Pantry — it never changes the recipe text, and re-saving the recipe returns every line to the first ingredient written on it.

Cross-references

A step can pull in another recipe’s steps. The embedded form sits inside a step on its own line:

## Make the sauce.

> @[Simple Tomato Sauce]

A bare @[Recipe Title] in prose — step text or footer — renders as a clickable link without embedding. The editor writes the embedded form for you from the row menu’s new cross-reference item; the full syntax, including multipliers and prep notes, is on Cross-references.

Links

Prose takes ordinary Markdown links — step instructions, ingredient and cross-reference prep notes, and the footer.

Adapted from [Bake with Jack](https://bakewithjack.co.uk).

A link address must be a web address (http:// or https://), a mailto: address, or an ftp:// address; any other scheme is rejected. A rejected link renders as the plain text you typed, brackets and all — the words stay, so fix the address and the link comes back. That covers a hand-typed path to another recipe, too: use @[Recipe Title], which links a recipe by title and isn’t affected.

Scalable numbers

A * after a number in step instructions, ingredient prep notes, cross-reference prep notes, or the footer marks it as scalable. When a reader changes the serving count, marked numbers update.

Divide the dough into 8* equal pieces.

- Eggs, 2: Beat with a fork until uniform, about 30* seconds.

> @[Pizza Dough], 2: Make a double batch — about 90* minutes total.

---

Yields about 12* cookies.

Numerals, fractions, and English number words from zero* through twelve* are all scalable. Type the * in the editor box the number lives in. See Scaling for what scales automatically without *.

Footer

The first --- on its own line ends the recipe body and starts the footer — the editor’s footer box. Everything after it is rendered as Markdown — good for notes, tips, and variations. Any link in it follows the rules under Links. Where the recipe came from has its own Source: line in the front matter, which renders just above the footer text.

That rule belongs to the text form, not to the editor. Type a --- on its own line into a step’s Instructions box and it renders as a thematic break, the way any other Markdown in that box does — nothing reads your instructions back as a recipe file, so nothing turns it into a footer. Reading the text is where the rule bites: paste a recipe whose instructions contain a ---, or hand-edit an exported .md that has one, and that line starts the footer and swallows everything after it. An export’s recipes/ copy is unaffected, so a --- in your instructions survives export and re-import.

---

A good basic pancake. Pairs well with @[Maple Syrup].

Things to know

• Front-matter keys (Category:, Tags:, Makes:, Serves:, Time:, Active:, Source:) parse only at the top, right after the description (or after the title if there’s none). Further down the recipe, a line that looks like front matter passes through as prose — so Active: keep whisking in a step won’t trip the parser. Inside the block, malformed or invalid shapes (serves: 4, Serves:4, Serves: 0, Time: varies) are still rejected, so a typo at the top doesn’t disappear silently
• When a recipe uses ## step headers, every ingredient bullet must sit under one. Bullets between the front matter and the first header are rejected; either move them under a header, or drop the headers and let the body read as one implicit step
• A description or step-instruction line that begins with - is written out exactly as you typed it. Reading that text back turns the line into an ingredient bullet, or stops the read with an error if it sits above the first step — so a dash-led line in prose is a shape to avoid if you plan to paste the text back or hand-edit the file. The footer is left alone either way — a bullet list there is ordinary footer content
• A step that contains both a > @[...] cross-reference and ingredients or instructions is rejected — the cross-reference must stand alone
• Only one > @[...] per step
• Even the one untitled step this format can spell — the whole recipe read as a single implicit step — loses that exemption when its content is a cross-reference: A step with a cross-reference needs a title.
• These three cross-reference rules are limits of the text form, not of the editor — there, a cross-reference can sit alongside a step’s own ingredients and instructions, and a step can hold more than one. A copy or an export still renders each cross-reference faithfully, in order, but reading that text back can’t reconstruct what the editor allowed: a step mixing a cross-reference with ingredients, a step holding more than one, and a cross-reference that opens an untitled first step are all rejected outright — the whole file fails, not just that step, and the error names the line to fix. An untitled step sitting alongside titled ones is the one shape that fails quietly: the text has no way to mark it, so its lines are read as part of the step above
• An export loses none of that. The .json copy in the archive’s recipes/ folder records the recipe exactly, and an import reads it in preference to the .md. Every limit on this page is a limit on reading the text — a pasted recipe, a hand-edited .md, or a .md you assembled yourself. See edit a recipe offline

See also

• Adding & editing recipes — the editor, where recipes are actually written
• Import a recipe with AI — bring in a recipe that isn’t in this format
• Markdown import — bring in files already written in this format
• Tags and categories — the full guide to the Category: and Tags: front-matter fields

Last updated August 30, 2026