Cooklang: A Recipe Format That Is Just a Text File

Quick answer

Cooklang is a markup language for recipes, and a Cooklang recipe is nothing more than a plain-text file with the .cook extension. You write ordinary sentences and mark the parts a program should understand: @ for ingredients, # for cookware, and ~ for timers.

Boil @eggs{2} for ~eggs{3%minutes}.
Mash the potatoes with a #potato masher{}.

The Cooklang about page describes it as "a markup language for recipes that makes it easy to manage your personal recipe collection." It started when its author, signing as Alex, was in quarantine in a small Irish coastal village. Online grocery shopping meant forgotten essentials and repetitive meal plans, so the answer was: "It's time to automate this… and never solve it twice."

How it actually works

The Cooklang specification is short. A recipe is a text file, and three symbols do most of the work.

Ingredients, cookware, and timers

Put @ in front of an ingredient. If the name has more than one word, end it with curly braces. Quantities go inside the braces, and a % separates the amount from its unit.

Poke holes in @potato{2}.
Place @bacon strips{1%kg} on a baking sheet.

Cookware works the same way with #. A single word needs no braces; a longer name does.

Place the potatoes into a #pot.
Mash the potatoes with a #potato masher{}.

Timers use ~, with the duration and unit inside the braces. A timer can also have a name, which apps can use in notifications.

Boil @eggs{2} for ~eggs{3%minutes}.

Read those lines aloud and they're still a recipe. That's the point of the design: the markers sit inside the sentences instead of replacing them.

Metadata and comments

Recipe details such as the title and tags go in a block at the top of the file, between two lines of three dashes. If you have used YAML front matter in Markdown, it looks the same.

---
title: Spaghetti Carbonara
tags: [pasta, dinner]
---

Notes to yourself use comments. A double dash comments out the rest of a line, and [- with -] makes a block comment that can sit in the middle of a sentence.

-- check the oven temperature
Slowly add @milk{4%cup} [- TODO change units to litres -], keep mixing

Recipes use .cook, and meal plans use .menu. Both are plain text.

What the tools do with the text

Because the structure is in the file, software can read it. The project lists a parser and command-line tool that turns .cook files into shopping lists organized by department, plus a web editor, a mobile app, and a web playground for trying the parser. None of that is required to write a recipe. It's a bonus you get for free.

When to use it (and when to skip it)

Use it when you want a recipe collection that you own. The about page puts the benefit this way: "Because Cooklang is just text, you can version control it, tweak it, and use it forever." A folder of .cook files can sit in Git, be copied between machines, and be backed up like any other plain-text notes.

It follows an idea you may know from Markdown. John Gruber created Markdown in 2004 to be an "easy-to-read and easy-to-write plain text format," one that can be published as plain text without looking like it is full of formatting instructions. Cooklang applies that thinking to the kitchen, and other formats do the same for other jobs, such as todo.txt for tasks and Fountain for screenplays.

There are honest reasons to skip it:

• The markers add noise. @bacon strips{1%kg} reads less smoothly than "1 kg bacon strips" when you see the raw file.
• You need tooling for the payoff. Shopping lists and timers come from a parser or app, not from the text alone.
• Occasional cooks gain little. Save only a handful of recipes? A plain note is enough.

One more caution: the about page does not state an open-source license, only a copyright notice for Cooklang. If you plan to build on the software, check the license in the project's GitHub repositories.

How Carets fits in

A .cook file is plain text, and keeping plain text portable is what Carets is for. Carets is a native notes and code editor for iPhone, iPad, and Mac, so you can read and edit a recipe file in the kitchen on one device and at your desk on another.

Two features help here. Carets organizes work into files, projects, and tags, so a folder of recipes can live as its own project and be filtered by tag. And it handles plain text and Markdown in one editor, so your recipe files sit beside your other notes without being converted into anything. Your files stay plain text, which keeps them future-proof.

Get Carets on the App Store for iPhone, iPad, and Mac and keep your first recipe as a text file.

Frequently Asked Questions

What file extension does Cooklang use?

Recipes are saved as .cook files, and meal plans use .menu. Both are plain text, so any editor opens them.

Do I need a special app to write Cooklang?

No. The format is just text, so any text editor works. Cooklang's own tools, such as the parser that builds shopping lists, are conveniences, not requirements.

How do I mark an ingredient with more than one word?

End the name with curly braces and put the quantity inside, as in this line from the spec:

Place @bacon strips{1%kg} on a baking sheet.

Can I add notes that don't show up in the recipe?

Yes. A double dash comments out the rest of a line, and [- with -] makes a block comment that can sit mid-sentence.