{"id":19211785,"url":"https://github.com/edibotopic/cook-labs","last_synced_at":"2025-05-12T20:11:20.792Z","repository":{"id":114296665,"uuid":"497342994","full_name":"edibotopic/cook-labs","owner":"edibotopic","description":"Prototype for a recipe documentation site. Recipes are written in CookLang syntax, parsed into JSON and then represented on a webpage. The prototype uses examples from molecular gastronomy.","archived":false,"fork":false,"pushed_at":"2023-07-28T09:44:04.000Z","size":754,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T02:53:45.937Z","etag":null,"topics":["cooking","cooklang","documentation","food","science"],"latest_commit_sha":null,"homepage":"https://edibotopic.github.io/cook-labs/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edibotopic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-28T14:35:14.000Z","updated_at":"2024-11-13T03:47:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"ba67195b-9510-474e-8ea2-81687c5728b5","html_url":"https://github.com/edibotopic/cook-labs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edibotopic%2Fcook-labs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edibotopic%2Fcook-labs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edibotopic%2Fcook-labs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edibotopic%2Fcook-labs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edibotopic","download_url":"https://codeload.github.com/edibotopic/cook-labs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249933547,"owners_count":21347698,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cooking","cooklang","documentation","food","science"],"created_at":"2024-11-09T13:44:42.522Z","updated_at":"2025-04-20T17:33:00.623Z","avatar_url":"https://github.com/edibotopic.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CookLabs\n\n**CookLabs** is a website designed to assist with recipe documentation, iteration and optimisation.\n\nIt is currently in prototype form and contains examples taken largely from the field of [molecular gastronomy](https://en.wikipedia.org/wiki/Molecular_gastronomy).\n\nThe website uses _mostly_ vanilla JavaScript, HTML and CSS. It is hoped that this will make it accessible as a pedagogical tool, especially for people who are not professional programmers.\n\n## How Does it Work\n\nEach recipe is stored in a structured plaintext format, written using the [Cooklang language specification](https://cooklang.org/docs/spec/).\n\n\u003e **Note**\n\u003e Please refer to the link above to understand how Cooklang recipes are written.\n\nThe user selects a recipe, which triggers the parsing of a source recipe (`.cook` file). The parsed recipe (in `.json` format) is then used to extract key information (metadata, equipment, ingredients, quantities) to be displayed on the\nwebsite.\n\nSource recipes are also shown in _Cooklang format_ to facilitate copying by users who might wish to recreate, modify or update the recipe. \n\n\u003e **Note**\n\u003e Syntax highlighters for `.cook` files are available for several text editors (Vim, VSCode, Obsidian), which makes writing Cooklang files easier (and more colorful).\n\nFor example, a recipe may contain a line as follows:\n\n```ruby\nCoagulate the @soy milk{} with @hydrochloric acid{2%splashes}\n-- TODO: ambiguous quantity\n```\n\nWhen this line is parsed it will output that two \"splashes\" of hydrochloric acid are required (ambiguous and possibly dangerous). The `--` signifies a comment in Cooklang, only intended to be read by humans. Subsequently, a collaborator may copy the recipe and submit the following revision:\n\n```ruby\nCoagulate the @soy milk{500%mL} with @1.0 N hydrochloric acid{25%mL}\n```\n\nThe revised version specifies precisely the **N**ormality (i.e, strength) as well as volume of hydrochloric acid required to achieve coagulation. Given that the files are stored in plaintext in a public repository, such collaboration and revision can benefit from Git(hub)-based [version control](https://www.atlassian.com/git/tutorials/what-is-version-control) practices.\n\n## Opinionated by Design\n\nThe approach to recipe creation for CookLabs is opinionated by design, demanding clarity and precision through the imposition of specific authoring standards.\n\n- Each recipe is written as a `.cook` file using the Cooklang language in accordance with the [Cooklang specification](https://cooklang.org/docs/spec)\n\n- The filename is written in :camel:CamelCase (e.g., `ApplePie.cook`) to facilitate parsing and to avoid issues with handling of spaces in filenames on different Operating Systems\n\n- All recipes contain essential metadata at the top, specifically the recipe _name_ and _author_. Other optional metadata can include (but is not limited to): _DSF formula_, _source information_, _preparation time_ and _tags_.\n\n- Times specified in the `~{\u003cnumber\u003e%units}` format should only follow a verb specifying an action. For example, the phrase `hydrate ~{2%hours}` will be translated into `hydrate for 2 hours` - in such cases there is no need to explicitly state 'for'.\n\n- Quantities should always be specified in precise terms, where possible, preferably using an SI unit of measurement. \"Sprinkles\" and \"spoonfuls\" are unlikely to yield sufficient clarity of expression and should be followed by a comment highlighting the need for revision.\n\n- Recipe names should be kept short and descriptive, preferably 1, 2 or --- if absolutely necessary --- 3 words long. Additional detail can be provided in the metadata as needed.\n\n### Comment: Recipes as Algorithms\n\nIn the computer science literature analogies between algorithms and recipes have frequently been made.\n\n\u003e Let us try to compare the concept of an algorithm with that of a cookbook recipe\n\u003e --- Donald Knuth from _The Art of Computer Programming_\n\nOften, however, recipes can generate an output in spite of deficiencies that would be fatal to a computer program. While ambiguous or poorly written code may not be compiled at runtime, a sloppy recipe can still produce a desirable outcome if the cook is sufficiently skilled. The latter case is more a testament to the interpretive capacities of humans than a demonstration that recipes do not require precision.\n\nIn the fields of food science and molecular gastronomy, it is often suggested that scientific recipes and \"formulations\" must be rendered more definite than their everyday counterparts. In other words: _scientists often aim to make the process of combining and transforming ingredients more algorithmic_. This may involve --- for example --- the precise specification of quantities and units.\n\nDespite this ambition, the documentation of recipes and methods in these fields remains inconsistent and scattered. While software-based approaches to managing recipes are used industrially, they often requires expensive proprietary software. This software is typically closed-source and not available to educators. Precise descriptions of formulations can be found in the scientific literature, but \"trivial\" details are often omitted and many of the articles are behind a paywall.\n\n\u003e **Note**\n\u003e Some links to other topics, tools and ideas relating to digital food can be [found here](https://github.com/edibotopic/digital-food)\n\n### Comment: Openness, Versioning and Education\n\nSoftware engineers have long understood the benefit of version control systems. Tools like _Git_ allow programmers to track and manage changes in their projects. These _local_ Git repositories can then be \"pushed\" to _remote_ repositories on services like GitHub and GitLab. Collaborators can read the code, copy or \"clone\" it to their own devices, highlight issues and submit suggested changes for review (\"pull requests\").\n\n[Many people use Git and GitHub for non-code projects](https://www.brendanschlagel.com/2018/09/28/repos-beyond-code-a-collection-of-creative-uses-of-github/) and [there are many food-related projects that can be found on Github](https://github.com/jzarca01/awesome-food). Gestures towards version control have been seen in food product development; for example, in its press releases the \"meal-replacer\" _Soylent_ has invoked versions, such as [Soylent Original Powder 1.9](https://soylent.com/blogs/news/original-powder-1-9-is-coming), although this functions --- at least in part --- as marketing rhetoric. In addition, it can be assumed that many food companies have some method to track different product iterations, although the methods for doing so --- where they do exist --- are opaque.\n\nThe goal for CookLabs, or similar implementations, should be the transparent documentation of recipe creation and innovation, in a manner that is open to educators, students and the public.\n\n## Similar Websites\n\nThere are several excellent implementations of the Cooklang markup language in web applications to document recipes. My initial research into some of these revealed sophisticated front-end frameworks and build systems that I did not fully understand :smile:, which was part of my motivation for creating this website. \n\nThe websites that I am aware of are:\n\n- [briansunter.com](https://briansunter.com/recipes/)\n- [net-mist-cooking-book](https://net-mist-cooking-book.netlify.app)\n- [nicholaswilde.io](https://nicholaswilde.io/recipes/)\n\nThe website in its current form would not be possible without:\n\n- The JavaScript/TypeScript parser for Cooklang recipes developed by [deathau](https://github.com/deathau/cooklang-js) that generates the `json`\n- The Cooklang language and supporting tools developed by [Alexey Dubovskoy](https://github.com/dubadub)\n- The authors of the [Handbook of Molecular Gastronomy](https://www.waterstones.com/book/handbook-of-molecular-gastronomy/roisin-burke/alan-kelly/9781466594784) which served as the source for several of the current example recipes\n- Free images taken from [Unsplash](https://unsplash.com)\n\n## Usage\n\n### Consuming\n\nSimply click around the website and find a recipe that interests you!\n\n### Contributing\n\n\u003e **Note**\n\u003e I plan on contributing *personally* to the website and do not imagine a significant volume of contributions from others at this point. If that changes I will be happy to facilitate issues and PRs.\n\nEach recipe is written in a file with the `.cook` extension\nin the `/recipes/` directory. Every recipe has an accompanying image in either `.png` or `.jpeg` format. A shell script `/recipes/popson.sh`\nextracts the names of the recipes and prints them to `/recipes/recipes.json`.\n\nThe names of the files are extracted from `recipes.json` and listed at the top of the page as buttons.\nClicking on \u003ckbd\u003eSparkling Meringue\u003c/kbd\u003e, for example, will automatically populate\nthe page with the relevant data from that recipe, namely:\n\n- Author\n- Equipment\n- Ingredients\n- Steps\n\nIf you want to contribute a recipe to the existing CookLabs site you can clone the repo, add your file and image to `/recipes/` and submit a pull request (PR). Alternatively, you can edit an existing recipe and submit a PR.\n\nThe raw Cooklang file is also printed with\nsyntax highlighting. The syntax highlighting is\na bit of a hack, as it uses the `Ruby` highlighter\nfrom `highlight.js`. I got this idea from [Brian Sunter's blog](https://briansunter.com/blog/cooklang/) on managing recipes in Git, where Ruby-based highlighting was also used for Cooklang markup.\n\nThis source code can be copied by clicking the red button in the top right corner of the markup block.\n\nRuby-based syntax highlighting is not perfect.\nSome issues include `#` commenting out everything that follows on a line, meaning that an Equipment\nname will be highlighted along with everthing that\nfollows on that line:\n\n```ruby\npierce the @apple then stew it in a #pot for five minutes\n```\n\nTo avoid this one can simply write the recipe as follows:\n\n```ruby\npierce the @apple then stew ~{5%min} in a #pot\n```\n\nA further issue is the highlighting of keywords from the Ruby language, such as `for` and `if`.\n\nAlas, it works OK for now and will have to do\nuntil I implement my own highlighter or at least a\nmodified/stripped-down version of the Ruby one.\n\n#### Use-case\n\nThe envisaged use-case is a laboratory, kitchen or business that\ncollaboratively generates and modifies recipes or methods.\n\nThere is an interest in cataloging this information in a\nconsistent manner, using an approach with the following\ncharacteristics:\n\n- **Consistent**: clearly enforced authoring style for content\n- **Versioned**: ability to track iterations of a given recipe\n- **Open**: information made available to internal and external collaborators\n- **Extensible**: code can be modified to fit user needs\n\nEach member of the team can clone the repository. They can write and\ntest recipes before submitting a `pull request` outlining the\npurpose of the recipe and the justification for its inclusion. A history of changes is automatically maintained by Git and Github.\nPull requests are reviewed and ones that are accepted are merged into\nthe recipes list.\n\nAlternatively,\na sufficiently novel deviation from an existing recipe may require a\nnew `branch` that can become a new recipe in its own right.\n\n### Building\n\nWhen a new `.cook` file is added the `/recipes/recipes.json`\nis updated when `make` invokes `popson.sh` in that directory.\n\nThe list of selectable recipes on the website depends on the existence of a suitably populated JSON,\nwhich means the makefile must be run before the site is\npushed to Github.\n\n```bash\ncd cook-labs\nmake\n```\n\nTo build the site yourself simply do a `git clone` and create\na remote repo on Github. Write your own `.cook` recipes using\nyour favourite text editor and save them to `/recipes/`. Style the website, give it a name and when\nyou're ready to push the contents run:\n\n```bash\nmake git m=\"your commit message here\"\ngit push origin main\n```\n\nNote: you will need to setup your repo as a GH-pages environment to\nshare the results.\n\n#### Cooklang CLI\n\nIf you have the [Cookang-CLI](https://github.com/cooklang/CookCLI) tool installed you can also simply\n`git clone` this repo, `cd` into `/recipes/` and run the\nfollowing command to print a recipe to your terminal:\n\n```bash\ncook recipe read \"AlginateBeads.cook\"\n```\n\nAlternatively, in the same directory you can run the\nfollowing to serve a local webpage:\n\n```bash\ncook server\n```\n\nThen open [http://127.0.0.1:9080](http://127.0.0.1:9080) in your browser.\n\n### Limitations\n\n#### Dependencies\n\nThe project has [jq](https://stedolan.github.io/jq/) as a dependency. This is used to parse the\nrecipe files and split the filename from the filetype. Platform-specific (Windows, Linux, Mac) versions of `jq` are available.\n\nWhen `make` is run in the root directory this invokes `popson.sh`,\nwhich itself runs `jq`.\n\nTo successfully run the `make` file you need to have `jq`\ninstalled and on your _path_. I have only tested this on Linux,\nso if you run into issues please let me know.\n\n#### Scale and Scope\n\nThis app is not written in the expectation that there will\nbe thousands of users. It is also not written for use-cases\nwhere enterprises wish to store recipe information securely\nand/or privately.\n\nIt is better suited for individuals or collaborators who wish\nto share, document and improve recipes or methods in a free and\nopen-source manner.\n\nLastly, this also functions simply as an *idea* of what formalising recipe development and documentation might look like, especially in fields such as food science and molecular gastronomy.\n\n### Roadmap\n\n- [ ] Add more _recipes_\n- [ ] Query use of vh and vw in css\n- [ ] Make more scalable (display only selections/previews)\n- [ ] Show info, source, pairing and tags\n- [ ] Fix CSS animation for images\n- [ ] Add note on images (source and representation)\n- [ ] _Methods_ page\n- [ ] _About_ page\n- [ ] Implement _tags_\n- [ ] _Style_ guide\n- [ ] Clean up code\n- [ ] Add diagrams to readme\n- [ ] Investigate other ideas (esp. generators)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedibotopic%2Fcook-labs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedibotopic%2Fcook-labs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedibotopic%2Fcook-labs/lists"}