h-recipe: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(dump of h-recipe spec page)
 
m (Fix: corrects syntaxhightlight lang attributes)
 
(29 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<entry-title>h-recipe</entry-title>
{{DISPLAYTITLE:h-recipe}}
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
----
----
<dfn style="font-style:normal;font-weight:bold">h-recipe</dfn> is a simple, open format for publishing recipes on the web. h-recipe is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML/HTML5.
<dfn style="font-style:normal;font-weight:bold">h-recipe</dfn> is a simple, open format for publishing recipes on the web. h-recipe is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.


h-recipe is the [[microformats-2]] replacement for [[hRecipe]].
h-recipe is the [[microformats2]] update to [[hRecipe]].
 
{{cc0-owfa-license}}


== Example ==
== Example ==
Here is a simple minimal recipe example:
Here is a simple minimal recipe example:


<source lang=html4strict>
<syntaxhighlight lang=html>
<article class="h-recipe">
<article class="h-recipe">
   <h1 class="p-name">Bagels</h1>
   <h1 class="p-name">Bagels</h1>
Line 22: Line 24:
     serves <data class="p-yield" value="4">four people</data>.</p>
     serves <data class="p-yield" value="4">four people</data>.</p>
    
    
   <div class="u-instructions">
   <div class="e-instructions">
     <ol>
     <ol>
       <li>Start by mixing all the ingredients together.</li>
       <li>Start by mixing all the ingredients together.</li>
Line 28: Line 30:
   </div>
   </div>
</article>
</article>
</source>
</syntaxhighlight>
 
Parsed JSON:
<syntaxhighlight lang=json>
{
  "items": [
    {
      "type": [
        "h-recipe"
      ],
      "properties": {
        "name": [
          "Bagels"
        ],
        "ingredient": [
          "Flour",
          "Sugar",
          "Yeast"
        ],
        "yield": [
          "4"
        ],
        "instructions": [
          {
            "value": "Start by mixing all the ingredients together.",
            "html": "<ol>      <li>Start by mixing all the ingredients together.</li>    </ol>"
          }
        ]
      }
    }
  ]
}
</syntaxhighlight>


=== Get started ===
=== Get started ===
Line 39: Line 73:
== Properties ==
== Properties ==


properties:
=== Core Properties ===
 
The following core h-entry properties have broad consensus and are broadly interoperably published and consumed:  
 
h-recipe properties, inside an element with class '''h-recipe''':
 
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfyies
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfies
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>u-photo</code>''' - an accompanying image
* '''<code>u-photo</code>''' - an accompanying image


Experimental properties with wide adoption
=== Experimental properties with wide adoption ===
* '''<code>p-summary</code>'''  - provides a short summary or introduction  
* '''<code>p-summary</code>'''  - provides a short summary or introduction  
* '''<code>p-author</code>''' - the person who wrote the recipe with <code>h-card</code>
* '''<code>p-author</code>''' - person who wrote the recipe, optionally embedded with <code>h-card</code> {{main|h-card}}
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* '''<code>p-category</code>''' - recipe categories/tags
* ...
* ...


For backward compatibility, microformats 2 parsers {{should}} detect the following root class name and property names. A microformats 2 parser may use existing microformats [[parsers]] to extract these properties. If an "h-recipe" is found, don't look for an "hrecipe" on the same element.
=== Proposed properties ===


compat root class name: <code id="hrecipe">hrecipe</code><br/>
The following properties are proposed additions based on various use-cases but are awaiting citations of use across multiple sites in the wild, and at least one reader / real world consuming code example:
properties: (parsed as '''p-''' plain text unless otherwise specified)
 
* <code>fn</code> - parse as '''<code>p-name</code>'''
* '''<code id="u-remix-of">u-remix-of</code>''' - the URL which the h-entry is considered a “remix” of. Optionally an embedded [[h-cite]]. The purpose of this in an h-recipe is to identify that this recipe is a remix, or based on another recipe, and giving appropriate citation to that individual. In theory, if this was an exact copy, the u-repost-of used in h-entry would apply.
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code>  - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>


== Status ==
== Status ==


'''h-recipe''' is a microformats.org draft specification. Public discussion on h-recipe takes place on [[h-recipe-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [http://microformats.org/discuss/mail/microformats-new/ microformats-new mailing list].
'''h-recipe''' is a microformats.org draft specification. Public discussion on h-recipe takes place on [[h-recipe-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.


h-recipe is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-recipes up with classic [[hRecipe]] classnames.
h-recipe is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-recipes up with classic [[hRecipe]] classnames.
Line 83: Line 115:


== Examples in the Wild ==
== Examples in the Wild ==
* [http://www.eliduke.com Eli Duke] has posted some h-[http://www.eliduke.com/recipes recipes] on his site:
** http://www.eliduke.com/recipes/kale-salad
** http://www.eliduke.com/recipes/hummus
** http://www.eliduke.com/recipes/wacky-cake
** http://www.eliduke.com/recipes/vegan-mac-and-cheese


* … add any h-recipe examples you find in the wild
* [https://cleverdevil.io Jonathan LaCour] has created several h-[http://cleverdevil.io/content/recipes recipes] using his Known plugin on his site:
** https://cleverdevil.io/2015/kentucky-maid-cocktail
 
* [https://makeitperfectly.com Perfect Company] marks up their recipes with h-recipe:
** https://makeitperfectly.com/drink/recipes/1a1913f6-6ba2-11e5-a3ed-f372faffcfa4
** https://makeitperfectly.com/bake/recipes/194a6cea-6ba2-11e5-a3ed-8367b69ac326
 
* [https://aaronparecki.com/recipes Aaron Parecki] has several recipes on his website
** https://aaronparecki.com/2020/06/01/19/banana-bread
** https://aaronparecki.com/2018/12/25/8/habanero-sauce
 
== Validating ==
{{h-spec-section-validating}}
 
== Implementations ==
This section is '''informative'''.
 
Tools for generating and consuming h-recipe. When it gets too big we can move it to a separate page like [[h-recipe-implementations]].
 
Consuming h-recipe (sites and tools that consume and do something with h-recipe)
* [https://developers.pinterest.com/docs/rich-pins/recipes/ Pinterest] supports h-recipe to create "rich pins"
* ... (stub)
 
Generating h-recipe (sites and tools that help produce and publish h-recipe)
* [https://github.com/cleverdevil/Known-Recipes Recipe post generator for Known CMS] by [https://cleverdevil.io Jonathan LaCour].
 
Advocacy - open source and other implementations which would benefit from h-recipe support or some degree of support has been requested - feel free to help implement these.
* OpenRecipes [https://github.com/fictivekin/openrecipes/issues/198 issue 198] feature request: update spider to parse for the original hRecipe microformat, and the new h-recipe microformats2 update
 
== Backward Compatibility ==
=== Publisher Compatibility ===
(stub)
=== Parser Compatibility ===
Microformats parsers {{should}} detect classic properties only if a classic root class name is found and parse them as microformats2 properties.
 
If an "h-recipe" is found, don't look for an "hrecipe" on the same element.
 
compat root class name: <code id="hrecipe">hrecipe</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code>  - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>
* <code>category</code>
* <code>rel=tag</code> - parse as '''<code>p-category</code>'''. While not a class name nor typical microformats property, rel=tag was the typical way to tag an hrecipe. Thus parsers should look for rel=tag hyperlinks inside an hrecipe, and take the last path segment of their "href" value as a value for a '''<code>p-category</code>''' property.


== Background ==
== Background ==
h-recipe is based on the existing [[hRecipe]] specification.
h-recipe is based on the existing [[hRecipe]] specification.


Line 94: Line 179:
* [[h-recipe-feedback]]
* [[h-recipe-feedback]]
* [[microformats-2]]
* [[microformats-2]]
* [[h-card]] can be nested in h-recipe
* [[h-card]] can be embedded in h-recipe
* [[hRecipe]] is the classic microformat replaced by h-recipe
* [[hRecipe]] is the classic microformat replaced by h-recipe
[[Category:Draft Specifications]]

Latest revision as of 23:52, 30 November 2022

Tantek Çelik (Editor)


h-recipe is a simple, open format for publishing recipes on the web. h-recipe is one of several open microformat draft standards suitable for embedding data in HTML.

h-recipe is the microformats2 update to hRecipe.

Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-03-28, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Example

Here is a simple minimal recipe example:

<article class="h-recipe">
  <h1 class="p-name">Bagels</h1>
  
  <ul>
    <li class="p-ingredient">Flour</li>
    <li class="p-ingredient">Sugar</li>
    <li class="p-ingredient">Yeast</li>
  </ul>
 
  <p>Takes <time class="dt-duration" datetime="1H">1 hour</time>,
     serves <data class="p-yield" value="4">four people</data>.</p>
  
  <div class="e-instructions">
    <ol>
      <li>Start by mixing all the ingredients together.</li>
    </ol>
  </div>
</article>

Parsed JSON:

{
  "items": [
    {
      "type": [
        "h-recipe"
      ],
      "properties": {
        "name": [
          "Bagels"
        ],
        "ingredient": [
          "Flour",
          "Sugar",
          "Yeast"
        ],
        "yield": [
          "4"
        ],
        "instructions": [
          {
            "value": "Start by mixing all the ingredients together.",
            "html": "<ol>       <li>Start by mixing all the ingredients together.</li>     </ol>"
          }
        ]
      }
    }
  ]
}

Get started

The class h-recipe is a root class name that indicates the presence of an h-recipe.

p-name, e-instructions, p-ingredient and the other property classnames listed below define elements as properties of the h-recipe.

See microformats-2-parsing to learn more about property classnames.

Properties

Core Properties

The following core h-entry properties have broad consensus and are broadly interoperably published and consumed:

h-recipe properties, inside an element with class h-recipe:

  • p-name - the name of the recipe
  • p-ingredient - describes one or more ingredients used in the recipe.
  • p-yield - Specifies the quantity produced by the recipe, like how many persons it satisfies
  • e-instructions - the method of the recipe.
  • dt-duration - the time it takes to prepare the meal described by the recipe.
  • u-photo - an accompanying image

Experimental properties with wide adoption

  • p-summary - provides a short summary or introduction
  • p-author - person who wrote the recipe, optionally embedded with h-card
    Main article: h-card
  • dt-published - the date the recipe was published
  • p-nutrition - nutritional information like calories, fat, dietary fiber etc.
  • p-category - recipe categories/tags
  • ...

Proposed properties

The following properties are proposed additions based on various use-cases but are awaiting citations of use across multiple sites in the wild, and at least one reader / real world consuming code example:

  • u-remix-of - the URL which the h-entry is considered a “remix” of. Optionally an embedded h-cite. The purpose of this in an h-recipe is to identify that this recipe is a remix, or based on another recipe, and giving appropriate citation to that individual. In theory, if this was an exact copy, the u-repost-of used in h-entry would apply.

Status

h-recipe is a microformats.org draft specification. Public discussion on h-recipe takes place on h-recipe-feedback and the #microformats irc channel on irc.freenode.net.

h-recipe is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-recipes up with classic hRecipe classnames.

Property Details

(stub, add any property explanations here)

dt-duration should be marked up using the duration microsyntax defined in HTML5. TODO: add more examples

hRecipe has a number of experimental properties which have real world adoption due to Google recipe search support of hRecipe. These are: summary, author, published and nutrition.

Examples in the Wild

Validating

Main article: validators

Test and validate microformats2 markup in general with:

Implementations

This section is informative.

Tools for generating and consuming h-recipe. When it gets too big we can move it to a separate page like h-recipe-implementations.

Consuming h-recipe (sites and tools that consume and do something with h-recipe)

  • Pinterest supports h-recipe to create "rich pins"
  • ... (stub)

Generating h-recipe (sites and tools that help produce and publish h-recipe)

Advocacy - open source and other implementations which would benefit from h-recipe support or some degree of support has been requested - feel free to help implement these.

  • OpenRecipes issue 198 feature request: update spider to parse for the original hRecipe microformat, and the new h-recipe microformats2 update

Backward Compatibility

Publisher Compatibility

(stub)

Parser Compatibility

Microformats parsers SHOULD detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-recipe" is found, don't look for an "hrecipe" on the same element.

compat root class name: hrecipe
properties: (parsed as p- plain text unless otherwise specified)

  • fn - parse as p-name
  • ingredient
  • yield
  • instructions - parse as e-
  • duration - parse as dt-
  • photo - parse as u-
  • summary
  • author - including compat root vcard in the absence of h-card
  • nutrition
  • category
  • rel=tag - parse as p-category. While not a class name nor typical microformats property, rel=tag was the typical way to tag an hrecipe. Thus parsers should look for rel=tag hyperlinks inside an hrecipe, and take the last path segment of their "href" value as a value for a p-category property.

Background

h-recipe is based on the existing hRecipe specification.

See Also