-
Notifications
You must be signed in to change notification settings - Fork 7
/
specification.md
246 lines (164 loc) · 6.6 KB
/
specification.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
# RecipeMD Specification
This is version 2.3.2 of the RecipeMD specification.
RecipeMD is a Markdown-based format for writing down recipes. It
defines a certain structure which a document must follow to be a
RecipeMD recipe.
All RecipeMD files shall follow the [commonmark] specification.
[commonmark]: https://commonmark.org
## Example
This example presents the basic format of a RecipeMD recipe
```markdown
# Guacamole
Some people call it guac.
*sauce, vegan*
**4 Servings, 200g**
---
- *1* avocado
- *.5 teaspoon* salt
- *1 1/2 pinches* red pepper flakes
- lemon juice
---
Remove flesh from avocado and roughly mash with fork. Season to taste
with salt, pepper and lemon juice.
```
- the title is noted as a first level header: `# Guacamole`
- the short description is noted as one or more paragraphs: `Some
people call it guac.`
- the tags are noted as paragraph containing only a comma seperated
list in italics: `*sauce, vegan*`
- the yield is noted as paragraph containing only a comma seperated
list in bold face: `**4 Servings, 200g**`
- the ingredients are noted as list items. The headings form the
titles of ingredient groups. The amount of each ingredient (if
given) is noted in italics. Amounts may be expressed as decimals
(dividers "." and ",") and fractions:
```markdown
- *1* avocado
- *.5 teaspoon* salt
- *1 1/2 pinches* red pepper flakes
- lemon juice
```
- anything following the second horizontal line is considered
instructions
## RecipeMD Data types
### Recipe
A *valid* recipe consists of:
- a title
- *optional*: a short description
- *optional*: 1..n tags
- *optional*: 1..n yields
- the ingredients as 1..n ingredient groups
- *optional*: instructions
A recipe is represented in markdown as follows:
1. Title as a first level heading
2. Short description as zero or more paragraphs
3. Yield and Tags (arbitrary order):
- Tags as a single paragraph which is completely in italics. Tags
are a comma separated list of strings.
- Yields as a single paragraph which is completely in bold. Yields
are a comma separated list of amounts. Note the rules about
commas in amounts.
5. a horizontal line
6. the ingredients, consisting of
1. *optional*: headings to group ingredients
2. lists, where each list item is an ingredient
7. a horizontal line -- this may be omitted if there are no
instructions
8. *optional*: the instructions, everything following the second line
### Amount
An amount consists of
- a value as a number
- *optional* a unit
An amount is represented as follows:
1. A number, which may have one of the following formats
- improper fraction (e.g. `1 1/5`)
- proper fraction (e.g `3/7`)
- [unicode vulgar fractions] (like ½) may also be used
- decimal with dividers "." and "," (e.g. "41.9")
2. A unit which is just everything following the number
[unicode vulgar fractions]: http://unicode.org/cldr/utility/list-unicodeset.jsp?a=[:Decomposition_Type=Fraction:]
Note that when an amount is inside of a comma separated list, a comma
is treated as a decimal divider if the characters directly before and
after are numerical and as a list divider otherwise.
### Ingredient
An ingredient consists of
- *optional* an amount
- a name
- *optional* a link to a recipe for the ingredient
An ingredient is represented as follows:
1. The amount in italics
2. Everything following until the end of the list item is part of the
name or the link as specified below:
1. If a name contains only an [inline-link], the [link-text]
represents the name of the ingredient and the [link-destination]
specifies a resource that contains a recipe for the ingredient
2. Otherwise, the text is the name and the link is not set
[inline-link]: https://spec.commonmark.org/0.28/#inline-link
[link-text]: https://spec.commonmark.org/0.28/#link-text
[link-destination]: https://spec.commonmark.org/0.28/#link-destination
### Ingredient Group
An ingredient group is a group of related ingredients, e.g. the
ingredients making up one component of a dish. It consists of:
- *optional* a title
- 1..n ingredients
An ingredient group us represented as follows:
1. A [heading], whose contents are the group's title
2. A list of ingredients
[heading]: https://spec.commonmark.org/0.28/#atx-headings
## Test Cases
Implementations of this specification must conform with all
[test cases]. There are two kinds of test cases: valid files (`*.md`
with a corresponding `*.json`) and invalid files (`*.invalid.md`)
[test cases]: https://github.com/tstehr/RecipeMD/tree/master/testcases
## Authors Licensing
This specification was written and is maintained by Jonas Grosse-Holz
and Tilman Stehr. The project's website is [recipemd.org].
The specification is licensed under the terms of the GNU Lesser
General Public License as published by the Free Software Foundation,
either version 3 of the License, or any later version.
[recipemd.org]: https://recipemd.org
## Version History
### Version 2.3.5 (2022-08-14)
- Fix test case "ingredients_multiline.md" to use valid link targets
- Expand test cases to cover
- [reference links] and [reference-style images]
- ingredients with sublists
- ingredients using numbered lists
- ingredients partially wrapped with links
- link ingredients with spaces in link targets
- link ingredients with link titles
- partial tag paragraphs that should not be interpreted as tags
- titles using [setext headings]
[reference links]: https://spec.commonmark.org/0.30/#reference-link
[reference-style images]: https://spec.commonmark.org/0.30/#example-581
[setext headings]: https://spec.commonmark.org/0.30/#setext-headings
### Version 2.3.4 (2021-12-26)
- Fixes to test cases:
- Add missing ingredient groups in JSON files
- Clean up formatting
- Fix missing indentation spaces for multiline ingredients
### Version 2.3.3 (2021-01-02)
- Clarify that yields and tags may appear at most once.
- Add test cases:
- Multiple yields or tags
- Tag/yield order
### Version 2.3.2 (2019-12-18)
- Add author and license information
### Version 2.3.1 (2019-11-18)
- Fix missing link
- Fix wrong indentation and word wrapping
### Version 2.3.0 (2019-11-18)
- Add a full version of the example
- Add version history reconstructed from git
- Add reference to test suite
### Version 2.2.0 (2019-04-22)
- Allow recipes to reference other recipes
### 2.1.0 (2019-03-25)
- Allow unicode vulgar fractions in ingredient amounts
### 2.0.1 (2018-09-17)
- Reword specification
- Clarify edge cases
### 2.0.0 (2018-09-13)
- *Breaking:* Seperate yields and tags into own paragraphs
### 1.0.0 (2018-08-26)
- Initial version