Cooklang — README
Just heads up, that not all latest language features supported in the apps yet. You can track progress at https://github.com/orgs/cooklang/projects/4
Conventions (shopping lists, pantry, scaling, pictures, canonical metadata)
About Cooklang
Cooklang is the markup language at the center of an open-source ecosystem for cooking and recipe management. In Cooklang, each text file is a recipe written as plain-english instructions with markup syntax to add machine-parsible information about required ingredients, cookware, time, and metadata.
The .cook recipe specification
Below is the specification for defining a recipe in Cooklang.
Ingredients
To define an ingredient, use the @ symbol. If the ingredient's name contains multiple words, indicate the end of the name with {}.
Then add @salt and @ground black pepper{} to taste.To indicate the quantity of an item, place the quantity inside {} after the name.
Poke holes in @potato{2}.To use a unit of an item, such as weight or volume, add a % between the quantity and unit.
Place @bacon strips{1%kg} on a baking sheet and glaze with @syrup{1/2%tbsp}.Now you can try Cooklang and experiment with a few things in the Cooklang Playground!
Steps
Each paragraph in your recipe file is a cooking step. Separate steps with an empty line.
A step,
the same step.
A different step.If you want to force a line break within a step, end the line with a backslash \. The backslash will be replaced with a newline character when rendered.
Lay out the @rice paper{1}.\
Top with @avocado{1/2}(sliced),\
@cucumber{1/2}(julienned),\
and @cooked shrimp{4}.This will render as multiple lines within a single step.
Comments
You can add comments up to the end of the line to Cooklang text with --.
-- Don't burn the roux!
Mash @potato{2%kg} until smooth -- alternatively, boil 'em first, then mash 'em, then stick 'em in a stew.Or block comments with [- comment text -].
Slowly add @milk{4%cup} [- TODO change units to litres -], keep mixingMetadata
Recipes are more than just steps and ingredients—they also include context, such as preparation times, authorship, and dietary relevance. You can add metadata to your recipe using YAML front matter, add --- at the beginning of a file and --- at the end of the front matter block.
---
title: Spaghetti Carbonara
tags:
- pasta
- quick
- comfort food
---Cookware
You can define any necessary cookware with #. Like ingredients, you don't need to use braces if it's a single word.
Place the potatoes into a #pot.
Mash the potatoes with a #potato masher{}.Timer
You can define a timer using ~.
Lay the potatoes on a #baking sheet{} and place into the #oven{}. Bake for ~{25%minutes}.Timers can have a name too:
Boil @eggs{2} for ~eggs{3%minutes}.Applications can use this name in notifications.
Conventions
Beyond the core language, the Cooklang ecosystem has common conventions for file types (.cook for recipes, .menu for meal plans), shopping list configuration, pantry inventory, recipe scaling, adding pictures, and canonical metadata keys. See conventions.md for details.
Advanced
Notes
To include relevant background, insights, or personal anecdotes that aren't part of the cooking steps, use notes. Start a new line with > and add your story.
> Don't burn the roux!
Mash @potato{2%kg} until smooth -- alternatively, boil 'em first, then mash 'em, then stick 'em in a stew.Sections
Some recipes are more complex than others and may include components that need to be prepared separately. In such cases, you can use the section syntax, e.g., ==Dough==. The section name and the = symbols after it are optional, and the number of = symbols does not matter.
= Dough
Mix @flour{200%g} and @water{100%ml} together until smooth.
== Filling ==
Combine @cheese{100%g} and @spinach{50%g}, then season to taste.Short-hand preparations
Many recipes involve repetitive ingredient preparations, such as peeling or chopping. To simplify this, you can define these common preparations directly within the ingredient reference using shorthand syntax:
Mix @onion{1}(peeled and finely chopped) and @garlic{2%cloves}(peeled and minced) into paste.Referencing other recipes
You can reference other recipes using the existing @ ingredient syntax. The path is relative to the root of the recipes directory, without the .cook extension:
Pour over with @./sauces/Hollandaise{150%g}.These preparations should be clearly displayed in the ingredient list, allowing you to get everything ready before you start cooking.
Optional ingredients and cookware
To mark an ingredient or a piece of cookware as optional, put ? straight after the @ or #:
Season with @salt and @?chilli flakes{1%pinch}.
Use a #?splatter guard{} if you have one.The ? is not part of the name. It works with every form of ingredient and cookware: single word (@?chives), multi-word (@?chilli flakes{}), with a quantity (@?chilli flakes{1%pinch}), and recipe references (@?./sauces/chimichurri{}). It must follow the sigil directly: @? thyme is plain text, and a ? anywhere else, as in Did you add the @salt{}?, is ordinary text.
Optionality belongs to each occurrence, not to the ingredient as a whole, so the same ingredient can be required in one step and optional in another. Required and optional amounts are listed separately instead of being added together:
Stir @parmesan{100%g} into the sauce.
Top with extra @?parmesan{50%g} before serving.This recipe needs parmesan 100 g, plus parmesan 50 g marked as optional. Optional components scale exactly like required ones.
Applications should mark optional items wherever ingredients and cookware are listed, leave optional ingredients off a shopping list unless the user chooses them (see shopping lists), and not count a missing optional ingredient as missing when matching recipes against a pantry. An optional recipe reference makes every ingredient of the referenced recipe optional.
Projects Which Use Cooklang
Syntax Highlighting
More options: See syntax highlighting documentation.
Roadmap
There's a GitHub board where we show what we're working on and what's next https://github.com/orgs/cooklang/projects/4.