~puer-robustus/fathub-data

#Fathub recipe & ingredient dataset

These are the data files for all the recipes and ingredients on whatarewehaving.today.

It was originally derived from the fathub.org dataset.

You can adapt a local copy of the dataset to your liking. Feel free to send your recipes to this mailing list if you want them listed on whatarewehaving.today. For more info, see contributing.

#Data structure

The data for a fathub static site are separated into two distinct objects: ingredient information pages and recipes. The ingredient information pages describe what an ingredient is and which diets (if any) apply to the ingredient. The recipes on the other hand describe what amounts of ingredients are used to prepare what dish in which steps. All ingredients used in a recipe, must have an ingredient information page. Ingredient information pages can be reused across different recipes.

The second version of the fathub recipe and ingredient data format supports internationalisation. This is accomplished by having translated copies of the dataset. The root folder of the repository contains a subdirectory for every language. The english language is the canonical dataset and if a translated version in another subdirectory exists that file will be preferred.

dataset
├── en
│   ├── ingredients
│   │   ├── example-ingredient.md
│   │   ├── category
│   │   │   ├── detailed-ingredient.md
│   │   │   └── another.md
│   └── recipes
│       ├── dutch # Cuisine subdirectory
│       │   └── main # Course subdirectory
│       │       └── boerenkool.toml # Recipe
├── nl
│   ├── ingredients
│   │   ├── example-ingredient.md # Translation of the EN page
│   └── recipes
│       └── dutch
│           └── main
│               └── boerenkool.toml # Dutch translated recipe
├── README.md
└── tools
    └── lint.py

#Ingredient info file format

#Recipe file format

The recipes are described in toml. Here's a complete example recipe:

name = "Stamppot Boerenkool"
author =  "Martijn Braam <martijn@brixit.nl>"
created = 2021-08-01
cuisine =  "Dutch"
course = "main"
preptime = 5
cooktime = 35
serves = 4

tips = [
    "If the [kale] isn't pre-cut you need about [kale:1:kg] and wash/cut it",
    "This dish can be made vegetarian by substituting the fried bacon with peanuts, add some butter to compensate for the lack of grease",
    "The dish works best with some floury potatoes such as Russet and Yukon Gold",
    "Traditionally this dish is served with 'rookworst' which doesn't seem to be really available internationally"
]

[ingredients]
  [ingredients.potatoes]
  id = "potatoes"
  amount = 2000
  unit = "g"
  prep = "peeled"
  [ingredients.kale]
  id = "vegetables/kale/curly"
  amount = 600
  unit = "g"
  [ingredients.water]
  id = "water"
  amount = 100
  unit = "mL"
  [ingredients.salt]
  id = "salt"
  amount = 10
  unit = "g"
  [ingredients.bacon]
  id = "meat/pork/bacon"
  amount = 250
  unit = "g"

[[instructions]]
    name = "cooking"
    steps = [
        "Put the [kale,water] and [salt] in a large pan with a lid and bring to a boil",
        "When the [kale] has shrunk enough, put the [potatoes] on top of them",
        "Cut the [bacon] in small strips and fry them until crispy",
        "Once the [potatoes] are done, pour off the cooking liquid, but keep it",
        "Crush the mass (with a potato masher) and mix them",
        "Add the cooking water back and add the [bacon] with all the grease"
    ]

#Metadata

The first keys in the file contain the main metadata of the recipe. Then a tips list that is rendered at the end of the recipe normally but has to be at the start of the recipe for toml syntax reasons.

#Ingredients

Then the ingredient list is added as a dictionary. The name inside the brackets is the name used to refer to the ingredient inside the recipe. The id is the path to the ingredient file inside the database.

For ingredients the following properties are supported:

amount: For ingredients that have a specific amount that needs to be added. The unit for this field is described in the unit field. unit: When the amount is specified this sets the unit. This can be one of:

L
mL
cup
teaspoon
tablespoon
fl oz
g
ounce
kg
piece

The frontend is able to convert the unit to whatever the user desires. If the specific weight for an ingredient is known in the database it's also possible to swich the display value between the weight and volume units.

In translated recipes the units should still be defined by these english terms

prep: This is a single line description of specific preperation of the ingredient. This can be "sliced" to denote the ingredient is assumed to be pre-sliced to avoid a list of these tasks in the recipe steps themselves.

#Steps

The next section in the file is the [[instructions]] list. There can be multiple of these sections to break up larger recipes into "chapters". The two supported properties are:

name: The name for this section. This can be a free text field for complicated recipes but should just be the "cooking" string for simple recipes to make it auto-translatable. Another predefined option is "preparation" for recipes with an extra preperation step.

steps: This is a list of strings, one for each of the steps in the recipe. The frontend will render every line in this as a step with a checkbox to mark your progress while cooking. The recipe lines are mostly plain text but there is a DSL for making references:

When square brackets are put around a word it's a reference to an ingredient in the list. This is used to have translated ingredient names in recipes even before the recipe itself is translated. It also stylizes the name of the ingredient slightly to make it stand out in the recipe listing. Multiple names can be added seperated by a comma as a shorthand for adding a list of ingredients.

It's also possible to reference a specific amount of the ingredient by using the [ingredient:amount:unit] format that will render the ingredient in the page consistently with changes done in the ingredient list by the user like swapping the unit or multiplying the recipe amounts by a factor.

The last part of the DSL is the double brackets for referring to another recipe. With [[dutch/main/boerenkool]] a link would be generated to the recipe with that specific path. This is mainly useful for referring to other recipes in the tips section.

#Contributing

You can add recipes to whatarewehaving.today by

# 1. cloning this repository (ideally as part of fathub; see the
#    respective repo for instructions):
$ git clone https://git.sr.ht/~puer-robustus/fathub-data dataset
# 2. setup a venv for the dataset repo with pre-commit installed (not
#    necessary if you have a development venv for the parent fathub
#    repo already):
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install pre-commit
# 3. install the pre-commit hooks once to run them upon every commit:
$ pre-commit install --install-hooks
# 3. add the required ingredients and recipes and commit them to your
#    local repo
# 4. send the patch(es) to the project's mailing list e.g. using
#    git send-email

Please be aware that by contributing to this repository you agree to release your work under CC0 into the public domain. Feel free to add yourself to .reuse/dep5 as a contributor.

refs

clone