microformats2: Difference between revisions
GRegorLove (talk | contribs) (→Implementations: microformats.io links, commented out Glenn's since it's not working currently) |
|||
(73 intermediate revisions by 22 users not shown) | |||
Line 1: | Line 1: | ||
< | <span style="float:right">__TOC__</span> | ||
Welcome to the | Welcome to the microformats2 home page. | ||
== Summary == | == Summary == | ||
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for <em>both</em> authors (publishers) and developers ([[microformats2-parsing|parser]] implementers). | |||
Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from [[microdata]] and [[RDFa]]. | |||
=== simple | === simple microformats2 examples === | ||
Here are a few simple | Here are a few <span id="simple_microformats_2_examples">simple microformats2 examples</span> along with canonical [[JSON]]. | ||
==== person example ==== | |||
* Simple person reference: | * Simple person reference: | ||
< | <syntaxhighlight lang="html"> | ||
<span class="h-card">Frances Berriman</span> | <span class="h-card">Frances Berriman</span> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 32: | Line 26: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
---- | ---- | ||
==== hyperlinked person ==== | |||
* Simple hyperlinked person reference | * Simple hyperlinked person reference | ||
< | <syntaxhighlight lang="html"> | ||
<a class="h-card" href="http://benward.me">Ben Ward</a> | <a class="h-card" href="http://benward.me">Ben Ward</a> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 53: | Line 48: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
---- | ---- | ||
==== hyperlinked person image ==== | |||
* Simple hyperlinked person image | * Simple hyperlinked person image | ||
< | <syntaxhighlight lang="html"> | ||
<a class="h-card" href="http://rohit.khare.org/"> | <a class="h-card" href="http://rohit.khare.org/"> | ||
<img alt="Rohit Khare" | <img alt="Rohit Khare" | ||
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" /> | src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" /> | ||
</a> | </a> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 73: | Line 69: | ||
"properties": { | "properties": { | ||
"name": ["Rohit Khare"], | "name": ["Rohit Khare"], | ||
"url": ["http://rohit.khare.org"], | "url": ["http://rohit.khare.org/"], | ||
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"] | "photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"] | ||
} | } | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
Additional simple cases details in [[microformats-2-implied-properties]]. | Additional simple cases details in [[microformats-2-implied-properties]]. | ||
Line 85: | Line 81: | ||
---- | ---- | ||
* More detailed person | ==== detailed person example ==== | ||
< | * More detailed person | ||
<syntaxhighlight lang="html"> | |||
<div class="h-card"> | <div class="h-card"> | ||
<img class="u-photo" alt="photo of Mitchell" | <img class="u-photo" alt="photo of Mitchell" | ||
Line 103: | Line 100: | ||
<span class="p-category">Leadership</span> | <span class="p-category">Leadership</span> | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 126: | Line 123: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
---- | ---- | ||
=== details from examples === | |||
Details demonstrated by the examples: | |||
# The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification. | # The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification. | ||
# all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property. | # all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property. | ||
=== microformats2 design === | |||
microformats2 has the following key design aspects: | |||
; Prefixes for class names | |||
: All microformats class names use prefixes. Prefixes are '''syntax independent from vocabularies''', which are developed separately. | |||
* <code>h-*</code> for root class names (e.g. <code>h-card</code>) | |||
* <code>p-*</code> for plain text properties (e.g. <code>p-name</code>) | |||
* <code>u-*</code> for URL properties (e.g. <code>u-photo</code>) | |||
* <code>dt-*</code> for date/time properties (e.g. <code>dt-bday</code>) | |||
* <code>e-*</code> for embedded markup properties (e.g. <code>e-note</code>)<br /> | |||
See [[microformats2-prefixes]] for more details. | |||
; Flat sets of optional properties | |||
: All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance). | |||
; Single class markup for common uses | |||
: Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties: <code>name</code>, <code>url</code>, <code>photo</code>. The simple microformats2 examples above demonstrate these. | |||
---- | |||
Parsing each prefix (including generating canonical JSON) is detailed step-by-step in: | |||
* The '''[[microformats2-parsing|microformats2 parsing specification]]''' | |||
'''Note:''' Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so! | |||
== v2 vocabularies == | == v2 vocabularies == | ||
Line 140: | Line 167: | ||
* [[h-entry]] | * [[h-entry]] | ||
* [[h-event]] | * [[h-event]] | ||
* [[h-feed]] | |||
* [[h-geo]] | * [[h-geo]] | ||
* [[h-item]] | * [[h-item]] | ||
* [[h-listing]] | |||
* [[h-product]] | * [[h-product]] | ||
* [[h-recipe]] | * [[h-recipe]] | ||
Line 172: | Line 201: | ||
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870) | * '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870) | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element. | ||
compat root class name: <code id="adr">adr</code><br/> | compat root class name: <code id="adr">adr</code><br/> | ||
Line 240: | Line 269: | ||
* ... | * ... | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element. | ||
compat root class name: <code id="vcard">vcard</code><br/> | compat root class name: <code id="vcard">vcard</code><br/> | ||
Line 322: | Line 351: | ||
(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>. | (*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>. | ||
For hAtom backward compatibility, | For hAtom backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element. | ||
compat root class name: <code id="hentry">hentry</code><br/> | compat root class name: <code id="hentry">hentry</code><br/> | ||
Line 381: | Line 410: | ||
(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>. | (*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>. | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element. | ||
compat root class name: <code id="vevent">vevent</code><br/> | compat root class name: <code id="vevent">vevent</code><br/> | ||
Line 411: | Line 440: | ||
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870) | * '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870) | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element. | ||
compat root class name: <code id="geo">geo</code> | compat root class name: <code id="geo">geo</code> | ||
Line 452: | Line 481: | ||
* '''<code>p-price</code>''' - retail price of the product | * '''<code>p-price</code>''' - retail price of the product | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element. | ||
compat root class name: <code id="hproduct">hproduct</code><br/> | compat root class name: <code id="hproduct">hproduct</code><br/> | ||
Line 491: | Line 520: | ||
* ... | * ... | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these 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/> | compat root class name: <code id="hrecipe">hrecipe</code><br/> | ||
Line 523: | Line 552: | ||
* '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization | * '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element. | ||
compat root class name: <code id="hresume">hresume</code><br/> | compat root class name: <code id="hresume">hresume</code><br/> | ||
Line 556: | Line 585: | ||
* '''<code>u-url</code>''' - URL of the review | * '''<code>u-url</code>''' - URL of the review | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element. | ||
compat root class name: <code id="hreview">hreview</code><br/> | compat root class name: <code id="hreview">hreview</code><br/> | ||
Line 570: | Line 599: | ||
* <code>worst</code> | * <code>worst</code> | ||
* <code>description</code> - parse as '''e-''' | * <code>description</code> - parse as '''e-''' | ||
* <code>rel=tag</code> - parse as '''p-category''' | * <code>rel="tag"</code> - parse as '''p-category''' | ||
* <code>rel="self bookmark"</code> - parse as '''u-url'''. note that <code>rel</code> attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted. | * <code>rel="self bookmark"</code> - parse as '''u-url'''. note that <code>rel</code> attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted. | ||
Note: The [[hReview]] format has three properties which make use of <code>rel</code> attribute, these are <code>tag</code>, permalink (via the <code>self</code> and <code>bookmark</code> values) and <code>license</code>. | Note: The [[hReview]] format has three properties which make use of <code>rel</code> attribute, these are <code>tag</code>, permalink (via the <code>self</code> and <code>bookmark</code> values) and <code>license</code>. Microformats2 parsers {{should}} map these URLs into the page scoped rel collection. | ||
=== h-review-aggregate === | === h-review-aggregate === | ||
Line 594: | Line 623: | ||
* '''<code>u-url</code>''' - URL of the review | * '''<code>u-url</code>''' - URL of the review | ||
For backward compatibility, | For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element. | ||
compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/> | compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/> | ||
Line 607: | Line 636: | ||
* <code>count</code> | * <code>count</code> | ||
* <code>votes</code> | * <code>votes</code> | ||
* <code>rel=tag</code> - parse as '''p-category''' | * <code>rel="tag"</code> - parse as '''p-category''' | ||
* <code>rel="self bookmark"</code> - parse as '''u-url'''. note that <code>rel</code> attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted. | * <code>rel="self bookmark"</code> - parse as '''u-url'''. note that <code>rel</code> attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted. | ||
Line 615: | Line 644: | ||
* All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules. | * All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules. | ||
* Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab). | * Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab). | ||
* | * microformats2 properties may also be explicitly bound as URIs using [[rel-profile]], the [[html5-profile]] attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on [[rel-profile]], [[html5-profile]], or contribute to an [[html5-vocab]] draft. | ||
=== v2 vocab to-do === | === v2 vocab to-do === | ||
Line 629: | Line 658: | ||
== combining microformats == | == combining microformats == | ||
Since | Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure. | ||
=== h-event location h-card === | === h-event location h-card === | ||
Events commonly have venue information with additional structure, like address information. For example: | Events commonly have venue information with additional structure, like address information. For example: | ||
< | <syntaxhighlight lang="html"> | ||
<div class="h-event"> | <div class="h-event"> | ||
<a class="p-name u-url" href="http://indiewebcamp.com/2012"> | <a class="p-name u-url" href="http://indiewebcamp.com/2012"> | ||
Line 650: | Line 679: | ||
</span> | </span> | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location. | The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location. | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 665: | Line 694: | ||
"end": ["2012-07-01"], | "end": ["2012-07-01"], | ||
"location": [{ | "location": [{ | ||
"value": "Geoloqi | "value": "Geoloqi", | ||
"type": ["h-card"], | "type": ["h-card"], | ||
"properties": { | "properties": { | ||
Line 679: | Line 708: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
Questions: | Questions: | ||
Line 701: | Line 730: | ||
with source: | with source: | ||
< | <syntaxhighlight lang="html"> | ||
<div class="h-card"> | <div class="h-card"> | ||
<a class="p-name u-url" | <a class="p-name u-url" | ||
Line 708: | Line 737: | ||
(<span class="p-org">Mozilla Foundation</span>) | (<span class="p-org">Mozilla Foundation</span>) | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 722: | Line 751: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
Sometimes such organization affiliations are hyperlinked to the website of the organization: | Sometimes such organization affiliations are hyperlinked to the website of the organization: | ||
Line 729: | Line 758: | ||
You can mark that up with a nested h-card: | You can mark that up with a nested h-card: | ||
< | <syntaxhighlight lang="html"> | ||
<div class="h-card"> | <div class="h-card"> | ||
<a class="p-name u-url" | <a class="p-name u-url" | ||
Line 738: | Line 767: | ||
>Mozilla Foundation</a>) | >Mozilla Foundation</a>) | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 759: | Line 788: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would. | Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would. | ||
Line 768: | Line 797: | ||
The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'. | The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'. | ||
< | <syntaxhighlight lang="html"> | ||
<div class="h-card"> | <div class="h-card"> | ||
<a class="p-name u-url" | <a class="p-name u-url" | ||
Line 777: | Line 806: | ||
>Mozilla Foundation</a>) | >Mozilla Foundation</a>) | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 798: | Line 827: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
Line 805: | Line 834: | ||
Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property: | Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property: | ||
< | <syntaxhighlight lang="html"> | ||
<div class="h-card"> | <div class="h-card"> | ||
<a class="p-name u-url" | <a class="p-name u-url" | ||
Line 814: | Line 843: | ||
>Mozilla Foundation</a>) | >Mozilla Foundation</a>) | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 834: | Line 863: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array. | Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array. | ||
Line 846: | Line 875: | ||
Or the nested object could be only marked up with 'h-card'. Source: | Or the nested object could be only marked up with 'h-card'. Source: | ||
< | <syntaxhighlight lang="html"> | ||
<div class="h-card"> | <div class="h-card"> | ||
<a class="p-name u-url" | <a class="p-name u-url" | ||
Line 855: | Line 884: | ||
>Mozilla Foundation</a>) | >Mozilla Foundation</a>) | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 875: | Line 904: | ||
}] | }] | ||
} | } | ||
</ | </syntaxhighlight> | ||
'''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].''' | '''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].''' | ||
Line 888: | Line 917: | ||
Simple hCards work just by adding <code>class="h-card"</code> : | Simple hCards work just by adding <code>class="h-card"</code> : | ||
< | <syntaxhighlight lang="html"> | ||
<span class="h-card">Frances Berriman</span> | <span class="h-card">Frances Berriman</span> | ||
Line 899: | Line 928: | ||
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/> | <img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/> | ||
</a> | </a> | ||
</ | </syntaxhighlight> | ||
* Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date. | * Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date. | ||
=== backward compatible === | === backward compatible === | ||
If you depend on current microformats [[implementations]], while they're being updated to support [[ | If you depend on current microformats [[implementations]], while they're being updated to support [[microformats2]], you can include both existing classic microformats and microformats2 markup. | ||
In short: use both sets of class names simultaneously. | In short: use both sets of class names simultaneously. | ||
Line 912: | Line 941: | ||
Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements: | Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements: | ||
< | <syntaxhighlight lang="html"> | ||
<span class="h-card vcard"> | <span class="h-card vcard"> | ||
<span class="p-name fn">Frances Berriman</span> | <span class="p-name fn">Frances Berriman</span> | ||
Line 932: | Line 961: | ||
</a> | </a> | ||
</span> | </span> | ||
</ | </syntaxhighlight> | ||
Line 948: | Line 977: | ||
Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]] | Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]] | ||
== extensions == | |||
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization. | |||
=== experimental extensions === | |||
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus: | |||
For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the <code>-x-</code> prefix before root and property class names. | |||
Specifically: | |||
* '*-x-' + '-' + meaningful name for root and property class names | |||
** where "*" indicates the single-character-prefix as defined above | |||
** where "x" indicates a literal 'x' for an experimental extension | |||
Examples: | |||
* "p-x-prep-time" - a possible experimental property name to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake. | |||
See [[microformats2-experimental-properties]] for more examples. | |||
=== <span id="VENDOR_EXTENSIONS">vendor extensions</span> === | |||
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'. | |||
* '*-x-' + '-' + meaningful name for root and property class names | |||
** where "*" indicates the single-character-prefix as defined above | |||
** where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character) | |||
Examples: | |||
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name. | |||
* "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.) | |||
See [[vendor-prefixes]] for more examples. | |||
=== extensions background === | |||
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes: | |||
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions] | |||
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type] | |||
* IETF MIME experimental fields (e.g. x-spam-score) | |||
* HTTP header extensions (e.g. x-pingback) | |||
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot] | |||
In particular: | |||
Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception. | |||
Proprietary or experimental CSS3 property implementations have been very successful. | |||
There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like: | |||
* -moz-border-radius | |||
* -webkit-border-radius | |||
etc. | |||
Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use. | |||
This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized. | |||
The benefits have been two-fold: | |||
* designers have been able to make more attractive sites sooner (at least in some browsers) | |||
* features have been market / real-world tested before being fully standardized, thus resulting in better features | |||
Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like: | |||
* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x]) | |||
* x-spam-score (in email headers) | |||
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback]) | |||
Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases: | |||
* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083]) | |||
See [[microformats2-origins#VENDOR_EXTENSIONS]] for more background. | |||
== validators == | == validators == | ||
Line 953: | Line 1,054: | ||
{{new}} Test your microformatted web page with: | {{new}} Test your microformatted web page with: | ||
* | * https://pin13.net/mf2/ | ||
Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed: | Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed: | ||
Line 966: | Line 1,067: | ||
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com] | * David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com] | ||
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is] | * [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is] | ||
* Ashton | * Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [https://acegiak.net/ acegiak.net] | ||
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com] | * Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com] | ||
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org] | * Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org] | ||
Line 979: | Line 1,080: | ||
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net] | * Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net] | ||
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC)) | * Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC)) | ||
* Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on [http://www.gutscheinflagge.de/ gutscheinflagge.de] | |||
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com] | * Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com] | ||
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com] | * Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com] | ||
Line 986: | Line 1,088: | ||
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org] | * Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org] | ||
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com] | * Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com] | ||
* Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example]) | * Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example]) | ||
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example]) | * App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example]) | ||
Line 1,012: | Line 1,113: | ||
=== offline === | === offline === | ||
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties | * spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties | ||
== Implementations == | == Implementations == | ||
Test your microformatted web page with: | |||
* | |||
=== Live Textarea Input === | |||
Use any of these to enter HTML+microformats2 markup and see the parsed result! | |||
* https://microformats.io hosts several of the parser libraries listed below for interactive testing | |||
** https://go.microformats.io | |||
** https://node.microformats.io/ | |||
** https://php.microformats.io/ | |||
** https://python.microformats.io/ | |||
** https://ruby.microformats.io/ | |||
** or look for "Parser Libraries" on the homepage | |||
* https://pin13.net/mf2/ (where it says "Microformats Parser") | |||
<!-- * http://glennjones.net/tools/microformats/ --> | |||
=== Blogging tools === | === Blogging tools === | ||
* '''Storytlr''' parses the | * '''Storytlr''' parses the <code>target</code> from [http://indiewebcamp.com/pingback pingbacks] for [https://github.com/storytlr/storytlr/blob/master/protected/application/public/controllers/PingbackController.php#L63 h-entry with properties and nested h-card] for information to automatically display in the [http://web.archive.org/web/20130425010536/http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html comments section on a post] (archived; [http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html original]). | ||
** Note: per storytlr.org, retrieved 2022-05-22: | |||
<blockquote>Storytlr is no longer maintained and '''might be unsafe to run on a public server'''. It is running on an old version of PHP and the Zend framework and has not been upgraded to latest versions and security patches.</blockquote> | |||
=== Converters === | === Converters === | ||
* '''[https://github.com/snarfed/granary granary]''' is a library and REST API that converts between silo APIs, [[ActivityStreams]], [[microformats2]], and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include [http://brid.gy/ Bridgy], [http://reader.kylewm.com/ Woodwind], and [https://facebook-atom.appspot.com/ facebook-atom] and [https://twitter-atom.appspot.com/ twitter-atom], among others. | |||
* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing]) | * '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing]) | ||
* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL | |||
=== Parsers === | === Parsers === | ||
Parsers, open source libraries: | Parsers, open source libraries, in alphabetical order by programming language: | ||
If you are implementing a microformats2 parser, see: | |||
* [[microformats2-parsing]] | |||
==== Parsers in production ==== | |||
The following parsers are of very high quality, in active development, and use on live sites on the web in production. | |||
==== Javascript ==== | ===== Java ===== | ||
* [[any23]] Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org | |||
===== Javascript ===== | |||
* '''microformats-parser''' for both browser and node.js | |||
** github open source: https://github.com/aimee-gm/microformats-parser (current) | |||
** live: https://aimee-gm.github.io/microformats-parser/ | |||
Previously: | |||
* '''microformat-node''' Node.js microformats2 parser | * '''microformat-node''' Node.js microformats2 parser | ||
** github open source: https://github.com/glennjones/microformat-node | ** github open source: https://github.com/microformats/microformat-node (current) | ||
*** forked from https://github.com/glennjones/microformat-node | |||
** test suite: https://github.com/microformats/tests | ** test suite: https://github.com/microformats/tests | ||
<!-- glennjones.net expired SSL cert as of 2018-358 or earlier | |||
** blog post: http://glennjones.net/2013/01/brand-new-microformats-2-parser/ | ** blog post: http://glennjones.net/2013/01/brand-new-microformats-2-parser/ | ||
** live: http://glennjones.net/tools/microformats/ | ** live: http://glennjones.net/tools/microformats/ | ||
* '''microformat-shiv''' - cross browser javascript | --> | ||
** http://microformatshiv.com/ | ** command line: https://github.com/JerrySievert/mf2 | ||
* '''microformat-shiv''' - cross browser javascript microformats2 parser which can also be used in browser extensions. | |||
<!-- ** http://microformatshiv.com/ Unresponsive 2018-358 or earlier --> | |||
** github open source: https://github.com/glennjones/microformat-shiv | ** github open source: https://github.com/glennjones/microformat-shiv | ||
==== PHP ==== | |||
===== PHP ===== | |||
* '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser | * '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser | ||
** github open source: https://github.com/indieweb/php-mf2 | ** github open source: https://github.com/indieweb/php-mf2 | ||
Line 1,042: | Line 1,180: | ||
** live: | ** live: | ||
*** textarea entry: http://waterpigs.co.uk/php-mf2/ | *** textarea entry: http://waterpigs.co.uk/php-mf2/ | ||
*** URL entry: | *** URL and textarea entry: https://pin13.net/mf2/ | ||
** [https://github.com/barnabywalters/php-mf-cleaner mf-cleaner]: functions for working with the raw mf2 data structure | |||
** | ===== Python ===== | ||
==== Python ==== | * '''mf2py''' Python microformats2 parser | ||
* ''mf2py'' Python microformats2 parser | |||
** main entry: [[mf2py]] | ** main entry: [[mf2py]] | ||
** github open source: https://github.com/tommorris/mf2py | ** github open source: https://github.com/tommorris/mf2py | ||
Line 1,053: | Line 1,190: | ||
*** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com] | *** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com] | ||
*** textarea entry: https://kartikprabhu.com/connection/mfparser | *** textarea entry: https://kartikprabhu.com/connection/mfparser | ||
*** another textarea: http://www.unmung.com/?html= | |||
*** URL and/or textarea: https://kylewm.com/services/mf2 | |||
===== Ruby ===== | |||
* '''indieweb/microformats-ruby''' Ruby microformats parser | |||
** github open source: https://github.com/indieweb/microformats-ruby | |||
** live text entry: https://microformats-parser-ruby.herokuapp.com | |||
===== Haskell ===== | |||
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser | |||
** github open source: https://github.com/myfreeweb/microformats2-parser | |||
** live textarea entry: https://unrelenting.technology/mf2/ | |||
==== Development parsers ==== | |||
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome! | |||
===== Erlang ===== | |||
* '''hazybluedot/mf2erl''' Erlang microformats2 parser | |||
** github open source: https://github.com/hazybluedot/mf2erl | |||
===== Elixir ===== | |||
* '''ckruse/microformats-elixir''' Elixir microformats2 parser | |||
** github open source: https://github.com/ckruse/microformats2-elixir | |||
===== Go ===== | |||
* '''willnorris/microformats''' Golang microformats2 parser | |||
** github open source: https://github.com/willnorris/microformats | |||
** live textarea entry: https://go.microformats.io/ | |||
===== Java ===== | |||
* '''Apache Any23''' a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2. | |||
** Download recent release: http://any23.apache.org/download.html | |||
** live: http://any23-vm.apache.org/ | |||
** source: http://any23.apache.org/build-src.html | |||
* '''mf2j''' An early-stage Java microformats2 parser | |||
** github open source: https://github.com/kylewm/mf2j | |||
** live: https://mf2j.herokuapp.com/?url={http://example.com} | |||
===== Perl ===== | |||
* '''Web::Microformats2''' Perl microformats2 parser | |||
** https://metacpan.org/pod/Web::Microformats2 | |||
** open source: https://github.com/jmacdotorg/microformats2-perl | |||
==== Experiments ==== | |||
Experiments and other proof of concept microformat2 parsing support. | |||
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser | |||
* ... | |||
=== Outreach === | |||
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom: examples with nested classes, e.g. microformats2] | |||
== Presentations == | == Presentations == | ||
Line 1,066: | Line 1,253: | ||
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote> | * <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote> | ||
== | == Origins == | ||
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats. | |||
This | |||
how | Now that [[microformats2-parsing]] is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years. | ||
* [[microformats2-origins]] | |||
== | == See Also == | ||
* [[microformats2]] | * [[microformats2]] | ||
* [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further. | * [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further. | ||
* [[microformats2-experimental-properties]] - listing experimental (-x- prefixed) properties and their use | |||
* [[microformats2-prefixes]] | * [[microformats2-prefixes]] | ||
* [[vendor-prefixes]] | |||
* [[microformats2-faq]] | * [[microformats2-faq]] | ||
* [[microformats2-parsing]] | * [[microformats2-parsing]] | ||
* 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]] | * 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]] |
Latest revision as of 19:05, 1 March 2024
Welcome to the microformats2 home page.
Summary
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for both authors (publishers) and developers (parser implementers).
Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from microdata and RDFa.
simple microformats2 examples
Here are a few simple microformats2 examples along with canonical JSON.
person example
- Simple person reference:
<span class="h-card">Frances Berriman</span>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Frances Berriman"]
}
}]
}
hyperlinked person
- Simple hyperlinked person reference
<a class="h-card" href="http://benward.me">Ben Ward</a>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Ben Ward"],
"url": ["http://benward.me"]
}
}]
}
hyperlinked person image
- Simple hyperlinked person image
<a class="h-card" href="http://rohit.khare.org/">
<img alt="Rohit Khare"
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" />
</a>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Rohit Khare"],
"url": ["http://rohit.khare.org/"],
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"]
}
}]
}
Additional simple cases details in microformats-2-implied-properties.
detailed person example
- More detailed person
<div class="h-card">
<img class="u-photo" alt="photo of Mitchell"
src="https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"/>
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="u-url"
href="https://twitter.com/MitchellBaker"
>@MitchellBaker</a>)
<span class="p-org">Mozilla Foundation</span>
<p class="p-note">
Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities.
</p>
<span class="p-category">Strategy</span>
<span class="p-category">Leadership</span>
</div>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"photo": ["https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"],
"name": ["Mitchell Baker"],
"url": [
"http://blog.lizardwrangler.com/",
"https://twitter.com/MitchellBaker"
],
"org": ["Mozilla Foundation"],
"note": ["Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities."],
"category": [
"Strategy",
"Leadership"
]
}
}]
}
details from examples
Details demonstrated by the examples:
- The JSON
"type"
uses the full microformat root class name (e.g."h-card"
) for consistent identification. - all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property.
microformats2 design
microformats2 has the following key design aspects:
- Prefixes for class names
- All microformats class names use prefixes. Prefixes are syntax independent from vocabularies, which are developed separately.
h-*
for root class names (e.g.h-card
)p-*
for plain text properties (e.g.p-name
)u-*
for URL properties (e.g.u-photo
)dt-*
for date/time properties (e.g.dt-bday
)e-*
for embedded markup properties (e.g.e-note
)
See microformats2-prefixes for more details.
- Flat sets of optional properties
- All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance).
- Single class markup for common uses
- Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties:
name
,url
,photo
. The simple microformats2 examples above demonstrate these.
Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:
Note: Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so!
v2 vocabularies
Status: draft. Please review and provide feedback in IRC.
- h-adr
- h-card
- h-entry
- h-event
- h-feed
- h-geo
- h-item
- h-listing
- h-product
- h-recipe
- h-resume
- h-review
- h-review-aggregate
See below for vocabulary summaries.
h-adr
The h-adr microformat is for marking up structured locations such as addresses, physical and/or postal. This is an update to adr.
root class name: h-adr
profile/itemtype: http://microformats.org/profile/h-adr
properties:
p-post-office-box
p-extended-address
p-street-address
p-locality
p-region
p-postal-code
p-country-name
p-label
- new in vCard4 (RFC6350)p-geo
(oru-geo
with a RFC 5870 geo: URL) - new in vCard4 (RFC6350)p-latitude
- new in vCard4 (RFC6350 from RFC 5870)p-longitude
- new in vCard4 (RFC6350 from RFC 5870)p-altitude
- new in vCard4 (RFC6350 from RFC 5870)
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element.
compat root class name: adr
properties: (parsed as p- plain text unless otherwise specified)
post-office-box
extended-address
street-address
locality
region
postal-code
country-name
h-card
The h-card microformat is for marking up people and organizations. This is an update to hCard.
root class name: h-card
profile/itemtype: http://microformats.org/profile/h-card
properties:
p-name
p-honorific-prefix
p-given-name
p-additional-name
p-family-name
p-sort-string
p-honorific-suffix
p-nickname
u-email
u-logo
u-photo
u-url
u-uid
p-category
p-adr
p-post-office-box
p-extended-address
p-street-address
p-locality
p-region
p-postal-code
p-country-name
p-label
p-geo
oru-geo
with a RFC 5870 geo: URL, new in vCard4 (RFC6350)p-latitude
p-longitude
p-altitude
- new in vCard4 (RFC6350 from RFC 5870)p-tel
p-note
dt-bday
u-key
p-org
p-job-title
- previously 'title' in hCard, disambiguated.p-role
u-impp
per RFC 4770, new in vCard4 (RFC6350)p-sex
new in vCard4 (RFC6350)p-gender-identity
new in vCard4 (RFC6350)dt-anniversary
new in vCard4 (RFC6350)- ...
Reserved properties: (properties not used much (if at all) in practice)
p-organization-name
p-organization-unit
p-tz
dt-rev
- ...
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.
compat root class name: vcard
properties: (parsed as p- plain text unless otherwise specified)
fn
- parse asp-name
honorific-prefix
given-name
additional-name
family-name
honorific-suffix
nickname
email
- parse as u-logo
- parse as u-photo
- parse as u-url
- parse as u-uid
- parse as u-category
adr
- parse asp-adr h-adr
including compat root classadr
extended-address
street-address
locality
region
postal-code
country-name
label
geo
- parse asp-geo h-geo
including compat root classgeo
latitude
longitude
tel
note
bday
- parse as dt-key
- parse as u-org
organization-name
organization-unit
title
- parse as p-job-titlerole
- ...
Reserved: (backward compat properties that parsers MAY implement, if they do, they MUST implement in this way:
tz
rev
- parse as dt-- ...
Note: use of 'value' within 'tel' should be automatically handled by the support of the value-class-pattern. And for now, the 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).
h-entry
The h-entry microformat is for marking up syndicatable content such as blog posts, notes, articles, comments, photos and similar. This is an update to hAtom.
root class name: h-entry
profile/itemtype: http://microformats.org/profile/h-entry
properties:
p-name
(was p-entry-title, see issues)p-summary
(was p-entry-summary, see issues)e-content
(was e-entry-content, see issues)dt-published
dt-updated
p-author
p-category
u-url
u-uid
p-geo
p-latitude
p-longitude
This is an update to hAtom.
Brainstorming:
The following properties are proposed additions to h-entry above and beyond what hAtom (or Atom) provides, based on various existing link preview markup conventions:
u-photo
u-audio
- consider special u- parsing rules for<audio>
u-video
- consider special u- parsing rules for<video>
u-in-reply-to
- for links to other posts that this post is a reply to (comment regarding, etc.)
Backward compatibility:
(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) SHOULD prefer p-name
over p-entry-title
, and use p-entry-title
value(s) as a fallback if there is no p-name
.
For hAtom backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element.
compat root class name: hentry
properties: (parsed as p- plain text unless otherwise specified)
entry-title
- parse asp-name
entry-summary
entry-content
- parse as e-published
- parse as dt-updated
- parse as dt-author
- including compat rootvcard
in the absence ofh-card
category
geo
- parse asp-geo h-geo
including compat rootgeo
latitude
longitude
- ...
FAQ:
- What is the
p-name
of a note?- A few options, from simplest to most detailed.
- same as the p-content/e-content property.
- same as the
title
element on the note permalink post page. When publishing a note on its own permalink post page, the contents of the note are likely abbreviated for the title of the page. The same abbreviation can be used for the p-name. - first sentence of the p-content/e-content property. It may be better for syndication and link-preview purposes to provide just the first sentence of the note as the
p-name
. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as thep-summary
.
- A few options, from simplest to most detailed.
- ...
Resolved Issues:
- 2012-245 Resolved. See 2012-243 IRC discussion/consensus for:
- Use
p-summary
instead ofp-entry-summary
. The historical semantic of "entry-summary" is not different from "summary" in any significant (or discernible way). Collapsing the two will simplify the overall microformats2 vocabularies further. In microformats2, entry-summary is no more. - Use
e-content
instead ofe-entry-content
. Same point and advantage. In microformats2, entry-content is no more. - drop
p-entry-title
. Unnecessary and subsumed by "p-name". Would consider move to backward compat only if cases are presented - known publishing uses are expected to be updated shortly.
- Use
h-event
The h-event microformat is for marking up events. This is an update to hCalendar.
root class name: h-event
profile/itemtype: http://microformats.org/profile/h-event
properties:
p-name
p-summary
(*)dt-start
dt-end
dt-duration
p-description
u-url
p-category
p-location
p-geo
p-latitude
p-longitude
- ...
This is an update to hCalendar.
(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) SHOULD prefer p-name
over p-summary
, and use p-summary
value(s) as a fallback if there is no p-name
.
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element.
compat root class name: vevent
properties: (parsed as p- plain text unless otherwise specified)
summary
- parse asp-name
dtstart
- parse asdt-start
dtend
- parse asdt-end
duration
- parse asdt-duration
description
url
- parse as u-category
location
- including compat rootvcard
in the absence ofh-card
, and compat rootadr
in the absence ofh-adr
geo
- parse asp-geo h-geo
including compat rootgeo
latitude
longitude
- ...
h-geo
The h-geo microformat is for marking up WGS84 geophysical coordinates. This is an update to geo.
root class name: h-geo
profile/itemtype: http://microformats.org/profile/h-geo
properties:
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element.
compat root class name: geo
properties: (parsed as p- plain text unless otherwise specified)
latitude
longitude
h-item
The h-item microformat is for marking up the item of an h-review or h-product. This is an update to part of hReview.
root class name: h-item
profile/itemtype: http://microformats.org/profile/h-item
properties:
p-name
u-photo
u-url
Note: in practice, due to the microformats2 implied property rules, it is expected that most uses of "h-item" won't require any explicit properties at all (since microformats2 parsers will infer name, photo, and url properties from the structure of the element with "h-item" and its contained content/elements if any).
h-product
The h-product microformat is for marking up products. This is an update to hProduct.
root class name: h-product
profile/itemtype: http://microformats.org/profile/h-product
properties:
p-name
- name of the productu-photo
- photo of the productp-brand
- manufacturer, can also be a nestedh-card
p-category
- freeform categories or tags applied to the item by the reviewere-description
u-url
- URL of the productu-identifier
- includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.p-review
- a review of the product, can also be a nestedh-review
p-price
- retail price of the product
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element.
compat root class name: hproduct
properties: (parsed as p- plain text unless otherwise specified)
fn
- parse asp-name
photo
- parse as u-brand
category
description
identifier
- parse as u-url
- parse as u-review
- including compat root classhreview
in the absence ofh-review
price
Note: hProduct has at least one experimental property which has real world adoption due to Google and Bing search support of hProduct. Currently this is: price
h-recipe
The h-recipe microformat is for marking up food recipes. This is an update to hRecipe.
root class name: h-recipe
profile/itemtype: http://microformats.org/profile/h-recipe
properties:
p-name
- the name of the recipep-ingredient
- describes one or more ingredients used in the recipe.p-yield
- Specifies the quantity produced by the recipe, like how many persons it satisfyiese-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 introductionp-author
- the person who wrote the recipe withh-card
dt-published
- the date the recipe was publishedp-nutrition
- nutritional information like calories, fat, dietary fiber etc.- ...
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these 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 asp-name
ingredient
yield
instructions
- parse as e-duration
- parse as dt-photo
- parse as u-summary
author
- including compat rootvcard
in the absence ofh-card
nutrition
Note: 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
h-resume
The h-resume microformat is for marking up resumes. This is an update to hResume.
root class name: h-resume
profile/itemtype: http://microformats.org/profile/h-resume
properties:
p-summary
- overview of qualifications and objectivesp-contact
- current contact info in anh-card
p-education
- an educationh-calendar
event, years, nestedh-card
of the school, location.p-experience
- a job or other professional experienceh-calendar
event, years, nestedh-card
of the organization, location, job-title.p-skill
- a skill or ability, optionally including level and/or duration of experiencep-affiliation
- an affiliation with anh-card
organization
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element.
compat root class name: hresume
properties: (parsed as p- plain text unless otherwise specified)
summary
contact
- including compat rootvcard
in the absence ofh-card
education
- including compat rootvevent
in the absence ofh-event
experience
- including compat rootvevent
in the absence ofh-event
skill
affiliation
- including compat rootvcard
in the absence ofh-card
Note: skill has a proposed expansion into competency with explicit summary, rating and/or duration components. Based on existing real world adoption, we should consider an h-competency vocabulary with p-summary, p-rating, and dt-duration properties.
h-review
The h-review microformat is for marking up reviews. This is an update to hReview. See also h-item.
root class name: h-review
profile/itemtype: http://microformats.org/profile/h-review
properties:
p-name
- name of the reviewp-item
- thing been reviewed i.e. business or person (h-card), event (h-event), place (h-adr or h-geo), product (h-product), website, url, or other item (h-item).p-reviewer
- person who authored the reviewdt-reviewed
- date time of when the review was writtenp-rating
- value from 1-5 indicating a rating for the item (5 best).p-best
- define best rating value. can be numerically lower than worst.p-worst
- define worst rating value. can be numerically higher than best.e-description
- the full text written evaluation and opinion of the reviewerp-category
- freeform categories or tags applied to the item by the revieweru-url
- URL of the review
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element.
compat root class name: hreview
properties: (parsed as p- plain text unless otherwise specified)
summary
parse asp-name
fn
- parse as p-name of the item being reviewed (p-item h-item p-name)photo
- parse as u-photo of the item being reviewed (p-item h-item u-photo)url
- parse as u-url of the item being reviewed (p-item h-item u-url)reviewer
- including compat root vcard in the absence of h-carddtreviewed
- parse as dt-rating
best
worst
description
- parse as e-rel="tag"
- parse as p-categoryrel="self bookmark"
- parse as u-url. note thatrel
attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted.
Note: The hReview format has three properties which make use of rel
attribute, these are tag
, permalink (via the self
and bookmark
values) and license
. Microformats2 parsers SHOULD map these URLs into the page scoped rel collection.
h-review-aggregate
The h-review-aggregate microformat is for marking up aggregate reviews of a single item. This is an update to hreview-aggregate. See also h-item.
root class name: h-review-aggregate
profile/itemtype: http://microformats.org/profile/h-review-aggregate
properties:
p-name
- name of the reviewp-item
- thing been reviewed i.e. business or person (h-card), event (h-event), place (h-adr or h-geo), product (h-product), website, url, or other item (h-item).p-rating
- value from 1-5 indicating average rating for the item (5 best).p-best
- define best rating value. can be numerically lower than worst.p-worst
- define worst rating value. can be numerically higher than best.p-count
- number of reviews aggregated.p-votes
- number of reviewers who have rated the product, thus contributing to the average rating.p-category
- freeform categories or tags applied to the item by the revieweru-url
- URL of the review
For backward compatibility, microformats2 parsers SHOULD detect the following root class name and property names. A microformats2 parser may use existing classic microformats parsers to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element.
compat root class name: hreview-aggregate
properties: (parsed as p- plain text unless otherwise specified)
summary
parse asp-name
fn
- parse as p-name of the item being reviewed (p-item h-item p-name)photo
- parse as u-photo of the item being reviewed (p-item h-item u-photo)url
- parse as u-url of the item being reviewed (p-item h-item u-url)rating
best
worst
count
votes
rel="tag"
- parse as p-categoryrel="self bookmark"
- parse as u-url. note thatrel
attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted.
v2 vocab notes
Notes:
- All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules.
- Profile URLs are provided for use with the HTML4
profile
attribute, microdataitemtype
attribute, and RDFavocab
&typeof
attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab). - microformats2 properties may also be explicitly bound as URIs using rel-profile, the html5-profile attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on rel-profile, html5-profile, or contribute to an html5-vocab draft.
v2 vocab to-do
To do:
- write a simple tutorial for creating/getting started with microformats-2 markup for new content
- examples in each h-* spec listed above of how to embed other microformats in them
- actual profile documents at http://microformats.org/profile/h-* URLs mentioned above.
- Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the sample vCard4/hCard1 microdata vocabulary. Also provide any necessary RDFa-specific language as needed. Both preferably in a generic vocabulary-independent way.
- write a porting guide mapping v1 property -> v2 property
- use-case: simple search/replace in templates (e.g. in case web author doesn't remember existing microformats vocabs and where they used them).
- advise using *both* in existing templates (e.g. in case some CSS depends on the existing microformats)
- analyzie/document how well the microformats2 model and vocabularies satisfy the use-cases used to design/create microdata.
combining microformats
Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure.
h-event location h-card
Events commonly have venue information with additional structure, like address information. For example:
<div class="h-event">
<a class="p-name u-url" href="http://indiewebcamp.com/2012">
IndieWebCamp 2012
</a>
from <time class="dt-start">2012-06-30</time>
to <time class="dt-end">2012-07-01</time> at
<span class="p-location h-card">
<a class="p-name p-org u-url" href="http://geoloqi.com/">
Geoloqi
</a>,
<span class="p-street-address">920 SW 3rd Ave. Suite 400</span>,
<span class="p-locality">Portland</span>,
<abbr class="p-region" title="Oregon">OR</abbr>
</span>
</div>
The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location.
Parsed JSON:
{
"items": [{
"type": ["h-event"],
"properties": {
"name": ["IndieWebCamp 2012"],
"url": ["http://indiewebcamp.com/2012"],
"start": ["2012-06-30"],
"end": ["2012-07-01"],
"location": [{
"value": "Geoloqi",
"type": ["h-card"],
"properties": {
"name": ["Geoloqi"],
"org": ["Geoloqi"],
"url": ["http://geoloqi.com/"],
"street-address": ["920 SW 3rd Ave. Suite 400"],
"locality": ["Portland"],
"region": ["Oregon"]
}
}]
}
}]
}
Questions:
- Should the nested hCard be present also as a top-level item in the JSON? - Tantek 02:02, 19 June 2012 (UTC)
- My current (2012-243) leaning is no. - Tantek 18:53, 30 August 2012 (UTC)
- If so, how do we avoid expansion of the JSON geometrically proportional to the depth of microformat nesting? (Or do we not worry about it?)
- Should there be a canonical hierarchical JSON and a canonical flattened JSON? - Tantek 02:02, 19 June 2012 (UTC)
- My current (2012-243) leaning is no, we stick with one canonical JSON for uf2 which is hierarchical. - Tantek 18:53, 30 August 2012 (UTC)
- If so, should the flattened JSON have references from properties to nested microformats that have been pushed to the top level per flattening? - Tantek 02:02, 19 June 2012 (UTC)
- If so, what convention does/do JSON follow for such synthetic local reference identifiers? - Tantek 02:02, 19 June 2012 (UTC)
Notes:
- The 'location' value reflects the visible text of its element, including spaces and punctuation, as well as the state abbreviation 'OR'. The 'h-card' property values are only what is marked up, and thus include structure values without extra punctuation, and the state takes the expanded form from the
title
attribute of its<abbr>
element.
h-card org h-card
People often publish information general to their company rather than specific to them, in which case, they may wish to encapsulate that in separately nested microformat. E.g. here is a simple h-card example with org property:
Mitchell Baker (Mozilla Foundation)
with source:
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<span class="p-org">Mozilla Foundation</span>)
</div>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": ["Mozilla Foundation"]
}
}]
}
Sometimes such organization affiliations are hyperlinked to the website of the organization:
Mitchell Baker (Mozilla Foundation)
You can mark that up with a nested h-card:
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <a href>
would.
FOR PARSERS ONLY:
The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'.
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card h-org"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card", "h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
FOR PARSERS ONLY:
Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property:
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card","h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array.
Such a nested microformat implies some relationship (containment, being related), but is not as useful as if the nested microformat was a specific property of its parent.
For this reason it's recommended that authors should not publish nested microformats without a property class name, and instead, when nesting microformats, authors should always specify a property class name (like 'p-org') on the same element as the root class name(s) of the nested microformat(s) (like 'h-card' and/or 'h-org').
FOR PARSERS ONLY:
Or the nested object could be only marked up with 'h-card'. Source:
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
TO DO: Add h-event h-card example and JSON, per real world publishing examples like Swing Time: Classes in Southern England.
authoring
minimal markup
The best way to use microformats-2 is with as little additional markup as possible. This keeps your code cleaner, improves its maintainability, and thus the quality and longevity of your microformats.
One big advantage of microformats-2 over previous microformats (and others) is the ability to add one class name to an existing element to create a structured item.
See the simple examples at the top for a start, e.g.
Simple hCards work just by adding class="h-card"
:
<span class="h-card">Frances Berriman</span>
<a class="h-card" href="http://benward.me">Ben Ward</a>
<img class="h-card" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
<a class="h-card" href="http://tantek.com">
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
</a>
- Tip: Inside an open tag, put the
class
attribute first, then any human text content attributes (e.g.alt
), then URL attributes (e.g.href
src
), and lastly other attributes (e.g.style
). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date.
backward compatible
If you depend on current microformats implementations, while they're being updated to support microformats2, you can include both existing classic microformats and microformats2 markup.
In short: use both sets of class names simultaneously.
When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.
Here are the microformats-2 hCards from above with current hCard markup as well, which may require adding a wrapping element (e.g. a <span>
) to separate the root class name element from explicit property class name elements:
<span class="h-card vcard">
<span class="p-name fn">Frances Berriman</span>
</span>
<span class="h-card vcard">
<a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>
<span class="h-card vcard">
<img class="p-name fn u-photo photo" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
</span>
<span class="h-card vcard">
<a class="u-url url" href="http://tantek.com">
<img class="p-name fn u-photo photo" alt="Tantek Çelik"
src="http://ttk.me/logo.jpg"/>
</a>
</span>
Tips:
- use the microformats-2 class name first, e.g.
class="h-card vcard"
class="u-url url"
- and pair them when using an element for multiple properties, e.g.:
class="p-name fn u-url url"
class="p-name fn u-photo photo"
- put microformats classes after classes for CSS (since page authors will likely interact more with their own classes for design than with microformats classes), e.g. as used on individual microformats events pages:
class="event-page h-event vevent"
The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition, and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is maintained over time.
Related FAQ: When using both h-card and vcard which should be first and why?
extensions
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization.
experimental extensions
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any experimental way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:
For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the -x-
prefix before root and property class names.
Specifically:
- '*-x-' + '-' + meaningful name for root and property class names
- where "*" indicates the single-character-prefix as defined above
- where "x" indicates a literal 'x' for an experimental extension
Examples:
- "p-x-prep-time" - a possible experimental property name to be added to h-recipe upon consideration/documentation of real-world usage/uptake.
See microformats2-experimental-properties for more examples.
vendor extensions
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'.
- '*-x-' + '-' + meaningful name for root and property class names
- where "*" indicates the single-character-prefix as defined above
- where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character)
Examples:
- "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
- "p-goog-preptime" - to represent Google's "preptime" property extension to hRecipe (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)
See vendor-prefixes for more examples.
extensions background
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes:
- CSS 2.1 4.1.2.1 Vendor-specific extensions
- IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [1]
- IETF MIME experimental fields (e.g. x-spam-score)
- HTTP header extensions (e.g. x-pingback)
- note also some critical thoughts from mnot
In particular:
Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.
Proprietary or experimental CSS3 property implementations have been very successful.
There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:
- -moz-border-radius
- -webkit-border-radius
etc.
Note that these are merely string prefixes, not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.
This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.
The benefits have been two-fold:
- designers have been able to make more attractive sites sooner (at least in some browsers)
- features have been market / real-world tested before being fully standardized, thus resulting in better features
Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and Wikipedia: HTTP header fields - non-standard headers (could use RFC reference instead) respectively, like:
- application/x-latex (per Wikipedia Internet media type: Type x)
- x-spam-score (in email headers)
- X-Pingback (per Wikipedia:Pingback)
Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:
- image/x-png (standardized as image/png, both per RFC2083)
See microformats2-origins#VENDOR_EXTENSIONS for more background.
validators
microformats2 validators:
new! Test your microformatted web page with:
Barnaby Walters has a hosted version of the open source php-mf2 parser where you can enter your markup into a textarea and see how it's parsed:
See the validators page for a longer list of validators.
Examples in the wild
Please add new examples in the wild of microformats-2 to the top of this list. When it gets too big we can move it to a separate page like microformats-2-examples-in-wild.
- ...
- David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on davidjohnmead.com
- Brian Suda marks up his blog posts up with h-entry and h-card on optional.is
- Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on acegiak.net
- Emma Kuo marks up her blog posts and notes with h-entry and h-card on notenoughneon.com
- Scott Jenson marks up his blog posts with h-entry and h-card on jenson.org
- Emily McAllen marks up her blog posts with h-entry and h-card on blackwoolholiday.com
- Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on snarfed.org
- Barry Frost marks up his notes with h-entry, h-card and h-cite on barryfrost.com
- Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on caseorganic.com
- Johannes Ernst marks up his blog posts with h-entry on upon2020.com
- Michiel de Jong marks up his profile and notes with h-entry and h-card on michielbdejong.com
- Mike Taylor marks up his profile and blog posts with h-card and h-entry on bear.im
- Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on erinjo.is
- Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on jeena.net
- Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on andysylvester.com (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --bw 14:44, 13 March 2014 (UTC))
- Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on gutscheinflagge.de
- Chloe Weil marks up her blog posts with h-entry on chloeweil.com
- Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on christopheducamp.com
- Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on glennjones.net
- Marcus Povey marks up his blog posts and profile with h-entry and h-card on marcus-povey.co.uk
- Eugen Busoiu marks up his web profile with h-card on eugenbusoiu.com]
- Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on notizblog.org
- Kyle Mahan marks up his profile and notes with h-card and h-entry on kylewm.com
- Emil Björklund marks up his blog posts with h-entry and h-card (example)
- App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 (example)
- Brett Comnes marks up his posts with h-entry and h-card (example)
- Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like (example)
- Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties (example)
- Laurent Eschenauer marks up his posts with h-entry (example)
- Tom Morris marks up his posts using h-entry (example)
- Sinolandquality marks up some of their content using h-feed and h-entry on sinolandquality.com
- W3Conf 2013 uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
- SemPress is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
- The Pastry Box Project use h-card and h-entry markup on their homepage and individual thoughts pages
- Tom Morris uses h-card and XFN to markup his blogroll.
- Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. 2012/230/reply/1.
- Tantek Çelik uses h-card, h-event, and h-entry on his home page, as well as h-entry on all post permalinks, e.g. 2012-243 post, with rel-prev/rel-next (if applicable) to indicate prev/next posts, and with rel-author to his home page with canonical hCard to indicate authorship.
- Barnaby Walters uses h-card on his home page, h-card, h-entry and XFN markup on his notes page.
- 2013-01-25 Barnaby Walters: Experimental Markup - describes how he's using microformats2 vocabularies:
h-adr
,h-card
,h-entry
,h-event
,h-geo
,h-review
, and experimental vocabularies:h-feed
(embedded for update histories), activity-streams objectsh-as-article
,h-as-collection
,h-as-note
,h-as-update
, as well as experimental properties:u-alternate
andu-as-downstream-duplicate
(links to POSSE copies), andu-in-reply-to
(links to content that the posts are in reply to).
- 2013-01-25 Barnaby Walters: Experimental Markup - describes how he's using microformats2 vocabularies:
- microformats.org at 7 years presentation with h-event and h-card markup for people and organizations.
- Rise of the Indie Web hCards (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has microformats-2 h-calendar and h-card markup
- WebMaker by Mozilla has microformats-2 h-calendar and h-card on event search (e.g. search near Portland Oregon) and event pages (e.g. IndieWebCamp 2012).[2]
- WebFWD by Mozilla has microformats-2 h-card markup on experts and team pages
- IndieWebCamp has microformats-2 h-event markup with nested h-cards for the organizers and the location.
- Mozilla Events page has microformats-2 h-event markup with attendees marked up with h-card.
- The Esri PDX Blog has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on project pages
offline
- spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties
Implementations
Test your microformatted web page with:
Live Textarea Input
Use any of these to enter HTML+microformats2 markup and see the parsed result!
- https://microformats.io hosts several of the parser libraries listed below for interactive testing
- https://go.microformats.io
- https://node.microformats.io/
- https://php.microformats.io/
- https://python.microformats.io/
- https://ruby.microformats.io/
- or look for "Parser Libraries" on the homepage
- https://pin13.net/mf2/ (where it says "Microformats Parser")
Blogging tools
- Storytlr parses the
target
from pingbacks for h-entry with properties and nested h-card for information to automatically display in the comments section on a post (archived; original).- Note: per storytlr.org, retrieved 2022-05-22:
Storytlr is no longer maintained and might be unsafe to run on a public server. It is running on an old version of PHP and the Zend framework and has not been upgraded to latest versions and security patches.
Converters
- granary is a library and REST API that converts between silo APIs, ActivityStreams, microformats2, and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include Bridgy, Woodwind, and facebook-atom and twitter-atom, among others.
- microformats to RSS - a Yahoo! pipe that converts a URL containing an h-feed containing h-entries, into an RSS feed (2013-10-21 blog post announcing)
- XRay (source code) - Returns a normalized representation of the microformats data at a URL
Parsers
Parsers, open source libraries, in alphabetical order by programming language:
If you are implementing a microformats2 parser, see:
Parsers in production
The following parsers are of very high quality, in active development, and use on live sites on the web in production.
Java
- any23 Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org
Javascript
- microformats-parser for both browser and node.js
- github open source: https://github.com/aimee-gm/microformats-parser (current)
- live: https://aimee-gm.github.io/microformats-parser/
Previously:
- microformat-node Node.js microformats2 parser
- github open source: https://github.com/microformats/microformat-node (current)
- forked from https://github.com/glennjones/microformat-node
- test suite: https://github.com/microformats/tests
- command line: https://github.com/JerrySievert/mf2
- github open source: https://github.com/microformats/microformat-node (current)
- microformat-shiv - cross browser javascript microformats2 parser which can also be used in browser extensions.
- github open source: https://github.com/glennjones/microformat-shiv
PHP
- php-mf2 - PHP microformats2 parser
- github open source: https://github.com/indieweb/php-mf2
- Packagist: https://packagist.org/packages/mf2/mf2
- live:
- textarea entry: http://waterpigs.co.uk/php-mf2/
- URL and textarea entry: https://pin13.net/mf2/
- mf-cleaner: functions for working with the raw mf2 data structure
Python
- mf2py Python microformats2 parser
- main entry: mf2py
- github open source: https://github.com/tommorris/mf2py
- live:
- URL entry: mf2py.herokuapp.com
- textarea entry: https://kartikprabhu.com/connection/mfparser
- another textarea: http://www.unmung.com/?html=
- URL and/or textarea: https://kylewm.com/services/mf2
Ruby
- indieweb/microformats-ruby Ruby microformats parser
- github open source: https://github.com/indieweb/microformats-ruby
- live text entry: https://microformats-parser-ruby.herokuapp.com
Haskell
- myfreeweb/microformats2-parser Haskell microformats2 parser
- github open source: https://github.com/myfreeweb/microformats2-parser
- live textarea entry: https://unrelenting.technology/mf2/
Development parsers
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome!
Erlang
- hazybluedot/mf2erl Erlang microformats2 parser
- github open source: https://github.com/hazybluedot/mf2erl
Elixir
- ckruse/microformats-elixir Elixir microformats2 parser
- github open source: https://github.com/ckruse/microformats2-elixir
Go
- willnorris/microformats Golang microformats2 parser
- github open source: https://github.com/willnorris/microformats
- live textarea entry: https://go.microformats.io/
Java
- Apache Any23 a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2.
- Download recent release: http://any23.apache.org/download.html
- live: http://any23-vm.apache.org/
- source: http://any23.apache.org/build-src.html
- mf2j An early-stage Java microformats2 parser
- github open source: https://github.com/kylewm/mf2j
- live: https://mf2j.herokuapp.com/?url={http://example.com}
Perl
- Web::Microformats2 Perl microformats2 parser
Experiments
Experiments and other proof of concept microformat2 parsing support.
Outreach
Presentations
Presentations about microformats2:
- 2013-01-24 Microformats 2 presentation by Barnaby Walters at the Exeter Web Meetup in Devon, UK.
- 2012-09-21 microformats2 & bits of HTML5: The Evolution Of Web Data presentation by Tantek Çelik (@t) at RefreshLX in Lisbon, Portugal.
- 2012-07-21 HTML5 and microformats2: The Evolution Of Web Data presentation by Tantek Çelik (@t) at Innovators of the Web conference in San Francisco, CA.
- 2012-07-14 HTML5 and microformats2: The Evolution Of Web Data presentation by Tantek Çelik (@t) at Open Web Camp IV in San Jose, CA.
Testimonials
To prove the web standards community can come up with better standards than the SE’s, compare this: http://microformats.org/wiki/microformats-2 with schema . org — Joost de Valk (@yoast) 2013-02-05 13:35
... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. — Joost de Valk (@yoast) 2013-02-05 13:49
... But damn Microformats2 are sexy. — Joost de Valk (@yoast) 2013-02-05 13:53
Origins
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats.
Now that microformats2-parsing is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years.
See Also
- microformats2
- microformats2-brainstorming - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
- microformats2-experimental-properties - listing experimental (-x- prefixed) properties and their use
- microformats2-prefixes
- vendor-prefixes
- microformats2-faq
- microformats2-parsing
- 2010-05-02 microformats 2.0 discussion session at FOO East