https://github.com/cooklang/spec
Home for Cooklang specification and general discussions about the ecosystem
https://github.com/cooklang/spec
cooklang
Last synced: 5 months ago
JSON representation
Home for Cooklang specification and general discussions about the ecosystem
- Host: GitHub
- URL: https://github.com/cooklang/spec
- Owner: cooklang
- License: mit
- Created: 2021-03-13T17:52:50.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-09T13:31:48.000Z (5 months ago)
- Last Synced: 2024-11-09T13:38:42.847Z (5 months ago)
- Topics: cooklang
- Homepage: https://cooklang.org
- Size: 97.7 KB
- Stars: 591
- Watchers: 17
- Forks: 10
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
- stars - cooklang/spec - Home for Cooklang specification and general discussions about the ecosystem (Others)
README
Table of Contents
=================
* [About Cooklang](#about-cooklang)
* [The .cook Recipe Specification](#the-cook-recipe-specification)
* [Ingredients](#ingredients)
* [Comments](#comments)
* [Metadata](#metadata)
* [Cookware](#cookware)
* [Timer](#timer)
* [The Shopping List Specification](#the-shopping-list-specification)
* [Conventions](#conventions)
* [Adding Pictures](#adding-pictures)
* [Projects Which Use Cooklang](#projects-which-use-cooklang)
* [Syntax Highlighting](#syntax-highlighting)
## 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}.
```
### 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.
```
### 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 mixing
```
### 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.
```
### Metadata
You can add metadata tags to your recipe for information such as source (or author), meal, total prep time, and number of people served.
```
>> source: https://www.gimmesomeoven.com/baked-potato/
>> time required: 1.5 hours
>> course: dinner
```
### 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.
## The Shopping List Specification
To support the creation of shopping lists by apps and the command line tool, Cooklang includes a specification for a configuration file to define how ingredients should be grouped on the final shopping list.
You can use `[]` to define a category name. These names are arbitrary, so you can customize them to meet your needs. For example, each category could be an aisle or section of the store, such as `[produce]` and `[deli]`.
```
[produce]
potatoes
[dairy]
milk
butter
```
Or, you might be going to multiple stores, in which case you might use `[Tesco]` and `[Costco]`.
```
[Costco]
potatoes
milk
butter
[Tesco]
bread
salt
```
You can also define synonyms with `|`.
```
[produce]
potatoes
[dairy]
milk
butter
[deli]
chicken
[canned goods]
tuna|chicken of the sea
```
## Conventions
There're things which aren't part of the language specification but rather common conventions used in tools build on top of the language.
### Adding Pictures
You can add images to your recipe by including a supported image file (`.png`,`.jpg`) matching the name of the recipe recipe in the same directory.
```
Baked Potato.cook
Baked Potato.jpg
```
You can also add images for specific steps by including a step number before the file extension.
```
Chicken French.cook
Chicken French.0.jpg
Chicken French.3.jpg
```
## Projects Which Use Cooklang
* [Cooklang playground](https://biowaffeln.github.io/cooklang-parser/)
* [Obsidian plugin](https://github.com/deathau/cooklang-obsidian)
* [Official command line application](https://github.com/cooklang/CookCLI)
* [Official iOS application](https://cooklang.org/app/)
## Syntax Highlighting
* [Emacs](https://github.com/cooklang/cook-mode)
* [Nano](https://github.com/le-jun/cooklang.nanorc)
* [SublimeText](https://github.com/cooklang/CookSublime)
* [Vim](https://github.com/luizribeiro/vim-cooklang)
* [VSCode](https://github.com/cooklang/CookVSCode)