Discussion for references inside recipes

[Chais]

I'm working on a tool to optimise recipes. For that I need info how steps depend on one another. I like RecipeMD because it's reasonable human-readable and -writable while also being machine-readable.
The info I'm after is how steps in the recipe depend on other steps or on ingredients, which I just view as steps without any dependencies/prerequisites.
I'm thinking of something like this:

# Lemon water

A glass of water with a slice of lemon.

*vegan*

**1 serving**

---

- *1* lemon <a name="lemon"></a>
- *1 glass* water <a name="water"></a> 

---

1. Cut the [lemon](#lemon) in half. <a name="halves"></a>
2. Cut a slice from one of the [halves](#halves), then stick them back together with their open faces, so they don't dry out or oxidise. <a name="slice"></a>
3. Add the [slice](#slice) to the [glass of water](#water).

Which would render as:

Lemon water

A glass of water with a slice of lemon.

vegan

1 serving

---

• 1 lemon
• 1 glass water

---

1. Cut the lemon in half.
2. Cut a slice from one of the halves, then stick them back together with their open faces, so they don't dry out or oxidise.
3. Add the slice to the glass of water.

Is this something that is already allowed by the specification? Would it interfere?

[tstehr]

Hi, thank you for considering basing your project on RecipeMD.

Is this something that is already allowed by the specification? Would it interfere?

The example recipe you've given is valid RecipeMD, as such I don't see a problem in using it.

I don't think I'd want to add references between steps and ingredients in this form to the core RecipeMD spec, but I can see it working perfectly fine as an add-on that does not interfere with the RecipeMD parser.

[Chais]

But is it something you'd consider adding in general? This specific format is just the first thing that came to my mind.
The way I see it there are two practical routes to approach this:

1. Every step gets an ID of some sort, like the <a> tag in this case, and every step references the IDs of all its direct dependencies.
2. Every step gets an ID of some sort and dependencies are specified at the end of the recipe.

I think first option offers a slightly better user experience. This would have to be written at least once, should one choose to use it.

Ideally, at least for my specific use-case, we could also consider a more generic approach that allows for arbitrary data to be associated with a chunk of text. Since RecipMD doesn't specify the format of the recipe itself, a chunk of text might be a block

--- 

First follow these simple steps, that I will describe over several lines  
[ foo="bar", bar=3 ]

Then do this and that.  
[ foo="baz", bar=5 ]

or an un-/ordered list.

--- 

1. First follow these simple steps, that I will describe over several lines  
[ foo="bar", bar=3 ]
2. Then do this and that.  
[ foo="baz", bar=5 ]

--- 

- First follow these simple steps, that I will describe over several lines  
[ foo="bar", bar=3 ]
- Then do this and that.  
[ foo="baz", bar=5 ]

If we can agree on a suitable format I'd be happy to work on a PR.

[tstehr]

But is it something you'd consider adding in general?

I'd be willing to consider it in general. However, there's a very limited amount of syntactic space that this feature could occupy, so I'll caution that it'll probably be quite difficult to get a good syntax for it.

As a note of guidance I'll point to my thoughts on the RecipeMD design philosophy in #47. I think similar concerns apply here:

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

In particular this means any new feature needs to either creatively re-use some existing markdown feature for its purposes (e.g. linked recipes, see #5) or add some specific plaintext that also reads well in source and when rendered (e.g. the "/" variant of alternative ingredients in #49).

Your suggested variant would create visible output in the rendered recipe that to me does not feel natural to authoring a recipe in markdown, so I'm against including it in the RecipeMD spec.

I could see a variant using heading links, but that would require using headings to structure the recipe.

I'm open to suggestions that fall within the design philosophy stated above. If it turns out we can't find any syntax that clears the (admittedly pretty high) bar for inclusion in the core RecipeMD spec, I'd love to still have this project use RecipeMD and specify its reference syntax as an extension to the spec.

[Chais]

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

I don't think this feature can fulfill this requirement. And even the commonmark specification doesn't fulfill it, as it allows for raw HTML tags.

Your suggested variant would create visible output in the rendered recipe that to me does not feel natural to authoring a recipe in markdown, so I'm against including it in the RecipeMD spec.

The two suggestions for attaching arbitrary data, yes. The original one with only the anchor doesn't.

I could see a variant using heading links, but that would require using headings to structure the recipe.

The issue I see with using only heading links is that they'll become unusable nearly immediately. As I understand it the anchor that's auto-generated is just the entire heading in lowercase and made URL-friendly. Meaning you'd have to repeat the step you want to reference in its entirety. And even if there's a length limit this approach probably becomes unwieldy quickly.

If we put aside the plain-text view for a moment our best bet is probably something involving raw HTML. The anchor lends itself to declaring the dependency. For arbitrary data we could either use comments (<!-- whatever you want -->), which don't render at all, or we could just attach arbitrary attributes to the anchor, avoiding those used by HTML (id, href, …). So one of these:

- *10 g* cinnamon <a name="cinnamon"></a><!-- some other stuff -->

---

1. Do something with the [cinnamon](#cinnamon)

or
---

- *10 g* cinnamon <a name="cinnamon" some="other stuff"></a>

---

1. Do something with the [cinnamon](#cinnamon)

• 10 g cinnamon

---

1. Do something with the cinnamon

or

• 10 g cinnamon

---

1. Do something with the cinnamon

I'd still consider that minimally intrusive in the plain-text format. But then again, I'm used to reading code, so I probably have a different definition of readability in that regard.

[tstehr]

I don't think any of the variants suggested so far clear my (admittedly pretty high) bar for inclusion in the core RecipeMD spec. I find it to be a rather niche use case that doesn't warrant taking up the amount of syntax space that the suggested variants require.

As said before that should in no way prevent you from building on top of RecipeMD as an add-on/extension. If you have any questions in that regard don't hesitate to contact me!