Using Git to manage and browse my recipes
A year ago I suddenly had to learn how to cook food. As we learned from Ratatouille, anyone can cook. And indeed, it’s not that hard to boil pasta or caramelize onions.
Yet over the months, I wanted to branch out to new foods and desserts. In particular, my crème brulee came out very nicely.
When browsing the Internet for new recipes, I found a lot of problems with the user experience:
- The amount of ingredients were often allocated for a family’s worth of servings. Living by myself, I would make too much.
- I’d have to read in-between the lines to see what equipment I would need, as I did not have a complete set.
- I would sometimes make substitutions, but have no way of modifying the recipe.
All of these were small nits which became more frustrating when actually trying to browse and read these sites. Each one is littered with ads and a rambling description at the top. I wanted a clean, easy-to-read experience.
What I really wanted was a way to modify these recipes. From a software engineering perspective, I modify code all the time using Git. I find some code, fork it, then push the fork. Sometimes the code is accepted upstream, or sometimes I maintain my own copy.
Why can’t we do this with recipes? I wondered. I put together dishout.recipes, a GitHub-hosted recipe viewer. That link takes you to the website, which includes documentation and some samples.
Everything starts with a GitHub repo and a cookbook JSON or YAML file. This cookbook file contains an index and organized list of every other recipe in the repository, also in JSON or YAML.
This results in a straightforward URL schema: http://dishout.recipes/g/fleker/personal-cookbook/crepe
This points to the repo fleker/personal-cookbook and then looks up the recipe labeled ‘crepe’. This format works for any GitHub repo, making it easy to fork my project or make your own.
I know that having to write recipes in YAML or JSON is a bit convoluted, and probably needs you to start from scratch. However, there are several benefits that you get in using a machine-readable format.
ingredients:
- item: Flour
amount: 0.75
unit: cup
By defining ingredients in this way, the website is able to automatically convert unit measurements to an approximation.
See that input field, right next to “Servings”? By changing that number, the ingredient amounts automatically update.
Below this section is one for equipment and then the numbered directions.
That’s it. There is nothing else you need. There are no ads nor any long paragraphs of text. You don’t need to login or create an account. You just get a clean, simple browser for your recipes.
By visiting one level up, such as http://dishout.recipes/g/fleker/personal-cookbook, you get the directory page by reading your .recipes.json file.
You can see everything nicely organized into categories that you define. This allows you to browse everything in the way you want.
To make this easier, the website itself is open source, while the docs page has a thorough definition of the schemas, JSON schema files, and an in-browser validator.
Do I expect a lot of people to start doing this? Maybe not. But I think that it’s better than the existing experience, so I’ll keep working on it.
