Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cooklang/spec

Home for Cooklang specification and general discussions about the ecosystem
https://github.com/cooklang/spec

cooklang

Last synced: 4 months ago
JSON representation

Home for Cooklang specification and general discussions about the ecosystem

Lists

README 

        
[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://vshymanskyy.github.io/StandWithUkraine)



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}.

```



### 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

```



### 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)