Discuss syntax for pair-shaped metadata

[tstehr]

Issue spun out of the discussion in PR #46.

There's a wish from some users to add some sort of structured metadata to recipes. Examples of metadata include:

• source
• times (baking, cooking, cooling, resting, active, total, …) (see also Add times for specification #27)
• taste
• vegetarian: yes/no
• nutrition information

Some of these can be incorporated into tags, e.g. by adding the taste as a tag or tagging a recipe as vegeratian. But that doesn't really work for pair-shaped metadata like times or nutrition information. For these the only solution currently is to put them into the recipe description, instructions or tags in an ad-hoc format. This has the drawback that different recipe author are going to choose different formats which is not bad per se but it would be nice to have a consistent format to enable tooling support.

State of the art

To figure out where recipe authors put data like this, I did an informal "survey" by looking at some cookbooks I own and recipe websites I tend to use:

• Recipe metadata usually occurs in these places (sorted by roughly by number of appearances in my non-representative sample)
  1. before the ingredient list
  2. after the instructions at the bottom of the page
  3. after the ingredient list
  4. after the recipe title before the description
• It's also common to split metadata by type, for example seriouseats.com puts cooking times with the yields before the ingredients, while nutrition information is located below the instructions.

Requirements for RecipeMD

From the discussion in #46 I extracted the following set of requirements that I'd like to satisfy

The overarching concern of adding a feature like this to RecipeMD is that it should feel natural and fit the way people might author their recipes in Markdown if not guided by the specification or tooling requirements.

• The source text should follow the markdown design philosophy:

  Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

  This includes using a minimal amount of additional required markup and retaining a natural reading order.

• The output of running the RecipeMD file to a commonmark renderer should look reasonable (e.g. converting to HTML or to PDF for printing via pandoc).

• The metadata format should allow tooling to do stuff with the metadata in a way that makes it more useful than ad-hoc metadata in the description.

• If the metadata embedded in RecipeMD uses a pre-existing format, it should fit with RecipeMD in spirit and be easy to understand and author.

Approaches

So far two approaches have been suggested. We're open for arguments for/against both of these and also for additional suggestions.

Extended Tags

In #46 I considered using tags as a more generic meta data field, by allowing colon-separated key-value-pairs there:

*vegan, summer, calories/serving: 39, protein/serving: 1.3 g, sugar/serving: 5.9 g,
fat/serving: 0.4 g, active time: 45 min, total time: 2h*

Metadata as fenced code blocks

In discussion with @AberDerBart an alternative approach came up. We could allow adding a fenced code block (aka ```-block) where tags and yields are currently located and parse its contents (as YAML or a something like that):

*vegan, summer*

```yaml
calories/serving: 39
protein/serving: 1.3 g
sugar/serving: 5.9 g
fat/serving: 0.4 g
active time: 45 min
total time: 2h
```

[blabug]

In discussion with @AberDerBart an alternative approach came up. We could allow adding a fenced code block (aka ```-block) where tags and yields are currently located and parse its contents (as YAML or a something like that):

I would advise against adding another big and complex language like YAML to the recipe format, as it enables too many possibilities than one would want (the possibility to just dump minified JSON into the fenced code blocks, referencing other fields, parser implementations that automatically convert Yes to true, but not Ja). Furthermore it feels off to embed a different language (vs. just representing the whole recipe as a valid yaml file. Would also ease the parsing from different programming languages).

As a third approach I would also suggest using bullet lists:

- Calories: 39
- Protein: 1.3 g
- Sugar: 5.9 g
- Fat: 0.4 g
- Active time: 45 min
- Total time: 2h

This has the idea, that it better resembles the table format, that you usually find those metadata in a recipe.

Also as seen above I don't really like the need having to specify /Serving every time. Looking at existing recipes I would rather consider allowing two metadata locations. One above the ingredients for unscaled metadata like cooking times, necessary utilities, difficulty and recipe source. And another at the recipe end for nutrition information like calories, proteins, sugar and fat. These will be automatically assumed to be 1 of the first amount specified. E.g. 4 Servings, 200g will specify this to be for 1 Serving instead of 1g. The recipe author may feel free to add an explanatory header or footer to the list to avoid confusion, if this is for one or multiple servings.

Last I wouldn't include booleans into these metadata, like vegetarian or vegan. It would create a redundancy, as currently tags already handle these usecases very well.