h-card: Difference between revisions
m (Minor tweaks to markup and phrasing) |
(→Properties: editorial: more explicit clarification of existing functionality that all properties are optional and plural meaning they may have multiple instances, not that each property instance takes multiple values (no one has ever implemented that, fortunately)) |
||
(32 intermediate revisions by 15 users not shown) | |||
Line 1: | Line 1: | ||
<dfn style="font-style:normal;font-weight:bold">h-card</dfn> is a simple, open format for publishing people and organisations on the web. h-card is often used on home pages and individual blog posts. h-card is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML. | |||
<dfn style="font-style:normal;font-weight:bold">h-card</dfn> is a simple, open format for publishing people and organisations on the web. h-card is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML | |||
h-card is the [[microformats2]] update to [[hCard]]. | h-card is the [[microformats2]] update to [[hCard]]. | ||
{{cc0-owfa-license}} | ;<span id="status">Status</span> | ||
:This is a '''Living Specification''' yet mature enough to encourage additional implementations and [https://github.com/microformats/h-card/issues feedback]. | |||
;<span id="participate">Participate</span> | |||
:[https://github.com/microformats/h-card/issues Open Issues] | |||
:[[IRC]] | |||
<div class="p-author h-card vcard"> | |||
;<span class="p-role role">Editor</span> | |||
:<span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> | |||
</div> | |||
;License | |||
: {{cc0-owfa-license}} | |||
<span style="float:right">__TOC__</span> | |||
== Example == | == Example == | ||
Here | Here are a couple of minimal examples: | ||
< | <syntaxhighlight lang=html> | ||
<a class="h-card" href=" | <a class="h-card" href="https://tantek.com/">Tantek Çelik</a>, | ||
</ | |||
<span class="h-card"> | |||
<a class="p-name p-org u-url" href="https://microformats.org/">microformats.org</a> | |||
</span> | |||
</syntaxhighlight> | |||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang=javascript> | ||
{ | { | ||
"items": [ | "items": [ | ||
{ | { | ||
"type": [ | "type": ["h-card"], | ||
"properties": { | "properties": { | ||
"name": [ | "name": ["Tantek Çelik"], | ||
"url": ["https://tantek.com/"] | |||
"url": [ | |||
} | } | ||
} | }, | ||
{ | { | ||
"type": [ | "type": ["h-card"], | ||
"properties": { | "properties": { | ||
" | "name": ["microformats.org"], | ||
"org": ["microformats.org"], | |||
"url": ["https://microformats.org/"] | |||
" | |||
"url": [ | |||
} | } | ||
} | } | ||
] | ] | ||
} | } | ||
</ | </syntaxhighlight> | ||
Note a single element was sufficient for the simple person example with implied name and URL properties, while for an organization, which requires a name and org, it needed explicit markup for the h-card and all properties, though still with only two elements. | |||
Nested h-card example | Nested h-card example: | ||
< | <syntaxhighlight lang=html> | ||
<div class="h-card"> | <div class="h-card"> | ||
<a class="p-name u-url" | <a class="p-name u-url" | ||
href=" | href="https://blog.lizardwrangler.com/" | ||
>Mitchell Baker</a> | >Mitchell Baker</a> | ||
(<a class="p-org h-card" | (<a class="p-org h-card" | ||
href=" | href="https://mozilla.org/" | ||
>Mozilla Foundation</a>) | >Mozilla Foundation</a>) | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang=javascript> | ||
{ | { | ||
"items": [{ | "items": [{ | ||
Line 105: | Line 71: | ||
"properties": { | "properties": { | ||
"name": ["Mitchell Baker"], | "name": ["Mitchell Baker"], | ||
"url": [" | "url": ["https://blog.lizardwrangler.com/"], | ||
"org": [{ | "org": [{ | ||
"value": "Mozilla Foundation", | "value": "Mozilla Foundation", | ||
Line 111: | Line 77: | ||
"properties": { | "properties": { | ||
"name": ["Mozilla Foundation"], | "name": ["Mozilla Foundation"], | ||
"url": [" | "url": ["https://mozilla.org/"] | ||
} | } | ||
}] | }] | ||
Line 117: | Line 83: | ||
}] | }] | ||
} | } | ||
</ | </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 126: | Line 92: | ||
For minimal examples where at most <code>p-name</code>, <code>u-url</code> and <code>u-photo</code> are required (such as the first given above), only the root class name is needed — see [[microformats-2-implied-properties|implied properties]]. | For minimal examples where at most <code>p-name</code>, <code>u-url</code> and <code>u-photo</code> are required (such as the first given above), only the root class name is needed — see [[microformats-2-implied-properties|implied properties]]. | ||
When more than those three minimal properties are needed, the root class name must be placed on an element which encloses all the desired properties, and then the properties themselves marked up using the classnames given below. | |||
See [[microformats2-parsing]] to learn more about property classnames. | See [[microformats2-parsing]] to learn more about property classnames. | ||
== Properties == | == Properties == | ||
h-card properties, inside an element with class '''h-card''': | h-card properties, inside an element with class '''h-card'''. All properties are both optional and may have multiple instances, e.g. multiple name, url, photo etc. properties. | ||
* '''<code>p-name</code>''' - The full/formatted name of the person or | * See [[microformats2-parsing]] to learn more about property classnames. | ||
<div style="margin-top:-.4em; float:right;"><span>Example h-card with common properties:</span> | |||
<ul style="list-style:none"><li><code><div class="'''h-card'''"></code> | |||
<ul style="list-style:none; margin-top:-.02em"> | |||
<li><code><span class="'''p-name'''">Sally Ride</span></code></li> | |||
<li><code><span class="'''p-honorific-prefix'''">Dr.</span></code></li> | |||
<li><code><span class="'''p-given-name'''">Sally</span></code></li> | |||
<li><code><abbr class="'''p-additional-name'''">K.</abbr></code></li> | |||
<li><code><span class="'''p-family-name'''">Ride</span></code></li> | |||
<li><code><span class="'''p-honorific-suffix'''">Ph.D.</span>,</code></li> | |||
<li><code><span class="'''p-nickname'''">sallykride</span> (IRC)</code></li> | |||
<li><code><div class="'''p-org'''">Sally Ride Science</div></code></li> | |||
<li><code><img class="'''u-photo'''" src="<nowiki>http://example.com/sk.jpg</nowiki>"/> </code></li> | |||
<li><code><a class="'''u-url'''" href="<nowiki>http://sally.example.com</nowiki>">w</a>,</code></li> | |||
<li><code><a class="'''u-email'''" href="<nowiki>mailto:sally@example.com</nowiki>">e</a> </code></li> | |||
<li><code><div class="'''p-tel'''">+1.818.555.1212</div></code></li> | |||
<li><code><div class="'''p-street-address'''">123 Main st.</div></code></li> | |||
<li><code><span class="'''p-locality'''">Los Angeles</span>, </code></li> | |||
<li><code><abbr class="'''p-region'''" title="California">CA</abbr>, </code></li> | |||
<li><code><span class="'''p-postal-code'''">91316</span></code></li> | |||
<li><code><div class="'''p-country-name'''">U.S.A</div></code></li> | |||
<li><code><time class="'''dt-bday'''">1951-05-26</time> birthday</code></li> | |||
<li><code><div class="'''p-category'''">physicist</div></code></li> | |||
<li><code><div class="'''p-note'''">First American woman in space.</div></code></li></ul></li> | |||
<li><code></div></code></li></ul> | |||
</div> | |||
Core properties: | |||
* '''<code>p-name</code>''' - The full/formatted name of the person or organization | |||
* '''<code>p-honorific-prefix</code>''' - e.g. Mrs., Mr. or Dr. | * '''<code>p-honorific-prefix</code>''' - e.g. Mrs., Mr. or Dr. | ||
* '''<code>p-given-name</code>''' - given (often first) name | * '''<code>p-given-name</code>''' - given (often first) name | ||
* '''<code>p-additional-name</code>''' - other | * '''<code>p-additional-name</code>''' - other (e.g. middle) name | ||
* '''<code>p-family-name</code>''' - family (often last) name | * '''<code>p-family-name</code>''' - family (often last) name | ||
* '''<code>p-sort-string</code>''' - string to sort by | * '''<code>p-sort-string</code>''' - string to sort by | ||
Line 141: | Line 135: | ||
* '''<code>p-nickname</code>''' - nickname/alias/handle | * '''<code>p-nickname</code>''' - nickname/alias/handle | ||
* '''<code>u-email</code>''' - email address | * '''<code>u-email</code>''' - email address | ||
* '''<code>u-logo</code>''' - a logo representing the person or | * '''<code>u-logo</code>''' - a logo representing the person or organization (e.g. a face icon) | ||
* '''<code>u-photo</code>''' | * '''<code>u-photo</code>''' - a photo of the person or organization | ||
* '''<code>u-url</code>''' - home page | * '''<code>u-url</code>''' - home page or other URL representing the person or organization | ||
* '''<code>u-uid</code>''' - universally unique identifier, | * '''<code>u-uid</code>''' - universally unique identifier, preferably canonical URL | ||
* '''<code>p-category</code>''' - category/tag | * '''<code>p-category</code>''' - category/tag | ||
* '''<code>p-adr</code>''' - postal address, optionally embed an [[h-adr]] {{main|h-adr}} | * '''<code>p-adr</code>''' - postal address, optionally embed an [[h-adr]] {{main|h-adr}} | ||
* '''<code>p-post-office-box</code>''' | * '''<code>p-post-office-box</code>''' - post office box description if any | ||
* '''<code>p-extended-address</code>''' - apartment/suite/room name/number if any | * '''<code>p-extended-address</code>''' - apartment/suite/room name/number if any | ||
* '''<code>p-street-address</code>''' - street number + name | * '''<code>p-street-address</code>''' - street number + name | ||
Line 171: | Line 165: | ||
* '''<code>dt-anniversary</code>''' | * '''<code>dt-anniversary</code>''' | ||
Experimental properties currently in use in the wild but not (yet) part of the official h-card spec. | |||
* '''<code>u-sound</code>''' - sound file containing the proper pronunciation of the name property, per vCard (RFC 6350). | |||
** Used by [https://vanderven.se/martijn/ Martijn van der Ven] with a clip of his given name. | |||
** Needs a GitHub issue to track. | |||
== Status == | == Status == | ||
'''h-card''' is a microformats.org draft specification. Public discussion on h-card takes place on [[ | '''h-card''' is a microformats.org draft specification. Public discussion on h-card takes place on the [[irc|#microformats channel on irc.freenode.net]] ([https://chat.indieweb.org/microformats view recent discussions]), and specific issues [https://github.com/microformats/h-card/issues may be filed on GitHub]. | ||
h-card is ready to use and implemented in the wild | h-card is ready to use and implemented in the wild. For backwards compatibility you should also mark up top-level h-cards as classic [[hCard]]s. | ||
== Property Details == | == Property Details == | ||
Line 184: | Line 182: | ||
<code>p-adr</code> can optionally embed an [[h-adr]] to cluster associated structured address properties. E.g. adding "p-adr" to the example earlier: | <code>p-adr</code> can optionally embed an [[h-adr]] to cluster associated structured address properties. E.g. adding "p-adr" to the example earlier: | ||
< | <syntaxhighlight lang=html> | ||
<div class="h-card"> | <div class="h-card"> | ||
<p class="p-name">Joe Bloggs</p> | <p class="p-name">Joe Bloggs</p> | ||
Line 193: | Line 191: | ||
</p> | </p> | ||
</div> | </div> | ||
</ | </syntaxhighlight> | ||
Q: Why would you use "p-adr" to cluster associated structured address properties? | Q: Why would you use "p-adr" to cluster associated structured address properties? | ||
A: Because if you have more than one structured address, | A: Because if you have more than one structured address, clustering which properties go with which address keeps them deterministically together, instead of depending on array indices or other heuristics. | ||
=== p-tel === | === p-tel === | ||
Line 209: | Line 207: | ||
=== Reserved properties === | === Reserved properties === | ||
The following properties were supported by the legacy hCard format, but were not carried over to h-card due to lack of real-world usage, or other problems. They are not part of h-card and should not be published, consumed, or proposed. | |||
* '''<code>p-organization-name</code>''' | * '''<code>p-organization-name</code>''' | ||
* '''<code>p-organization-unit</code>''' | * '''<code>p-organization-unit</code>''' | ||
* '''<code>p-tz</code>''' | * '''<code>p-tz</code>''' — timezone offset | ||
** <q>it's going to be a hard one to "get right", as the way timezones work in vcard/ical is very weird, and timezones as a whole are an iffy thing to denote (quite the disconnect between complexity, automated processing ability, actually representing what a user would want to show/display or already does on their homepage, and actually representing something useful to parse and do something with)</q> | |||
** <q>there's certainly no ecosystem of publishers & consumers supporting p-tz in any meaningful interoperable way</q> — [https://chat.indieweb.org/microformats/2021-06-22/1624385751126500 tantek in #microformats] | |||
* '''<code>dt-rev</code>''' | * '''<code>dt-rev</code>''' | ||
== Examples in the wild == | == Examples in the wild == | ||
Real world in the wild examples: | See also: [https://indieweb.org/h-card#IndieWeb_Examples h-card Examples on indieweb.org] | ||
Real world in the wild examples of sites and services that publish or consume h-card: | |||
* ... add uses of h-card you see in the wild here. | * ... add uses of h-card you see in the wild here. | ||
* | * [http://www.securityjobslondon.co.uk Security Jobs London] uses h-card with legacy [[hCard]] fallback markup (to satisfy [https://search.google.com/structured-data/testing-tool Google's Structured Data Testing Tool]) in the footer of each page | ||
* Brett Comnes marks up his posts with h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example]) | * Brett Comnes marks up his posts with h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example]) | ||
* Ben Werdmuller marks up his homepage and posts with h-card [http://werd.io/view/51d5097fbed7ded0633a5956 example]) | * Ben Werdmuller marks up his homepage and posts with h-card [http://werd.io/view/51d5097fbed7ded0633a5956 example]) | ||
* | * [https://joelpurra.com/ Joel Purra] uses a hidden h-card with legacy [[hCard]] fallback markup (to satisfy [https://search.google.com/structured-data/testing-tool Google's Structured Data Testing Tool]) on the front page | ||
* [http://eschnou.com/ Laurent Eschenauer] marks his homepage profile up using h-card | * [http://eschnou.com/ Laurent Eschenauer] marks his homepage profile up using h-card | ||
* [http://tommorris.org/ Tom Morris] marks himself up with h-card as well as venues he’s checked into ([http://tommorris.org/posts/8408 example]) | * [http://tommorris.org/ Tom Morris] marks himself up with h-card as well as venues he’s checked into ([http://tommorris.org/posts/8408 example]) | ||
* [ | * [https://www.w3.org/conf/ W3Conf 2013] uses h-card for all the event speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties. | ||
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-* | * [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-* | ||
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card markup on their homepage and individual thoughts pages | * [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card markup on their homepage and individual thoughts pages | ||
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll]. | * Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll]. | ||
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [ | * Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [https://aaronparecki.com/2012/230/reply/1 2012/230/reply/1]. | ||
* [ | * [https://tantek.com/ Tantek Çelik] uses h-card on his home page as well as within [[h-entry]]s on permalink pages to indicate authorship. | ||
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, as well as within h-entries for notes and articles, both to indicate authorship and also when mentioning people within the body of the notes. | * [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, as well as within h-entries for notes and articles, both to indicate authorship and also when mentioning people within the body of the notes. | ||
* [ | * [https://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with and h-card markup for people and organizations. | ||
* [ | * [https://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats2]] h-card markup | ||
* WebMaker by Mozilla has [[microformats2]] h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585] | * WebMaker by Mozilla has [[microformats2]] h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585] | ||
* WebFWD by Mozilla has [[microformats2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages | * WebFWD by Mozilla has [[microformats2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages | ||
* [ | * [https://indiewebcamp.com IndieWebCamp] has [[microformats2]] h-event markup with embedded h-cards for the organizers and the location. | ||
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats2]] h-event markup with attendees marked up with h-card. | * [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats2]] h-event markup with attendees marked up with h-card. | ||
* [https://tristanthomas.me Tristan Thomas] uses h-card on his home page | * [https://tristanthomas.me Tristan Thomas] uses h-card on his home page | ||
Line 246: | Line 248: | ||
=== offline === | === offline === | ||
* spreadly marks up share permalink pages with minimal h-cards inside h-entry | * spreadly marks up share permalink pages with minimal h-cards inside h-entry | ||
* 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]) | |||
* Sandeep Shetty marks his homepage and posts up with h-card and h-entry ([https://sandeep.io/101 example]) | |||
== Validating == | == Validating == | ||
* '''[ | * '''[https://indiewebify.me/validate-h-card/ indiewebify.me h-card validator]''' parses [[h-card]] markup and makes suggestions for things to add, with code samples | ||
{{h-spec-section-validating}} | {{h-spec-section-validating}} | ||
== Implementations == | |||
Software implementations that publish or consume h-card, including themes, plugins, or extensions: | |||
(This section is a stub that needs expansion! In practice, nearly every CMS on every [https://indieweb.org/ indie web] site supports publishing h-card by default, and most sites which support receiving webmentions parse h-card for authorship data.) | |||
When adding an implementation, please provide and link to its home page and open source repo if any. | |||
* [https://gnu.io/social/ GNUsocial] [https://git.gnu.io/gnu/gnu-social/ source code] | |||
* [https://hubzilla.org/hubzilla/ Hubzilla] [https://github.org/redmatrix/hubzilla source code] | |||
* [http://friendica.com/ Friendica] [https://github.org/friendica/friendica source code] | |||
* [https://github.com/dissolve/inkblot InkBlot] | |||
* [https://aperture.p3k.io/ Aperture] consumes h-card to show authorship information of feed posts ([https://github.com/aaronpk/Aperture/ source code]) | |||
* [https://xray.p3k.app/ XRay] consumes h-card and flattens it into a more minimal format ([https://github.com/aaronpk/XRay/ source code]) | |||
* [https://withknown.com/ Known] publishes and consumes h-card to show authorship of posts and responses | |||
* [https://brid.gy/ Bridgy] publishes microformats-2 versions of siloed content (including h-card for authorship) for consumption by mf2-consumers | |||
* [https://webmention.io/ webmention.io] consumes h-card for authorship data of incoming webmentions which it accepts on behalf of other sites | |||
* ... | |||
* ... | |||
== Backward Compatibility == | == Backward Compatibility == | ||
Line 255: | Line 277: | ||
For backward compatibility, you may wish to use classic [[hCard]] classnames in addition to the more future-proof h-card properties, for example: | For backward compatibility, you may wish to use classic [[hCard]] classnames in addition to the more future-proof h-card properties, for example: | ||
< | <syntaxhighlight lang=html> | ||
<p class="h-card vcard"> | <p class="h-card vcard"> | ||
<span class="p-name fn">Joe Bloggs</span>, | <span class="p-name fn">Joe Bloggs</span>, | ||
Line 261: | Line 283: | ||
... | ... | ||
</p> | </p> | ||
</ | </syntaxhighlight> | ||
The class '''<code>vcard</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[hCard]]. | The class '''<code>vcard</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[hCard]]. | ||
Line 320: | Line 342: | ||
== Additions == | == Additions == | ||
We've tried very hard with h-card to stay compatible with vCard4, and thus additions should be proposed on the vCard4 mailing list. | We've tried very hard with h-card to stay compatible with the vCard4 vocabulary, and thus additions should be proposed on the vCard4 mailing list. | ||
However, you may still use this wiki to capture additions for h-card here: | However, you may still use this wiki to capture additions for h-card here: |
Latest revision as of 17:09, 23 May 2024
h-card is a simple, open format for publishing people and organisations on the web. h-card is often used on home pages and individual blog posts. h-card is one of several open microformat draft standards suitable for embedding data in HTML.
h-card is the microformats2 update to hCard.
- Status
- This is a Living Specification yet mature enough to encourage additional implementations and feedback.
- Participate
- Open Issues
- IRC
- License
- Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-09-09, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.
Example
Here are a couple of minimal examples:
<a class="h-card" href="https://tantek.com/">Tantek Çelik</a>,
<span class="h-card">
<a class="p-name p-org u-url" href="https://microformats.org/">microformats.org</a>
</span>
Parsed JSON:
{
"items": [
{
"type": ["h-card"],
"properties": {
"name": ["Tantek Çelik"],
"url": ["https://tantek.com/"]
}
},
{
"type": ["h-card"],
"properties": {
"name": ["microformats.org"],
"org": ["microformats.org"],
"url": ["https://microformats.org/"]
}
}
]
}
Note a single element was sufficient for the simple person example with implied name and URL properties, while for an organization, which requires a name and org, it needed explicit markup for the h-card and all properties, though still with only two elements.
Nested h-card example:
<div class="h-card">
<a class="p-name u-url"
href="https://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="https://mozilla.org/"
>Mozilla Foundation</a>)
</div>
Parsed JSON:
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["https://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["https://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.
Get started
The class h-card
is a root class name that indicates the presence of an h-card.
For minimal examples where at most p-name
, u-url
and u-photo
are required (such as the first given above), only the root class name is needed — see implied properties.
When more than those three minimal properties are needed, the root class name must be placed on an element which encloses all the desired properties, and then the properties themselves marked up using the classnames given below.
See microformats2-parsing to learn more about property classnames.
Properties
h-card properties, inside an element with class h-card. All properties are both optional and may have multiple instances, e.g. multiple name, url, photo etc. properties.
- See microformats2-parsing to learn more about property classnames.
<div class="h-card">
<span class="p-name">Sally Ride</span>
<span class="p-honorific-prefix">Dr.</span>
<span class="p-given-name">Sally</span>
<abbr class="p-additional-name">K.</abbr>
<span class="p-family-name">Ride</span>
<span class="p-honorific-suffix">Ph.D.</span>,
<span class="p-nickname">sallykride</span> (IRC)
<div class="p-org">Sally Ride Science</div>
<img class="u-photo" src="http://example.com/sk.jpg"/>
<a class="u-url" href="http://sally.example.com">w</a>,
<a class="u-email" href="mailto:sally@example.com">e</a>
<div class="p-tel">+1.818.555.1212</div>
<div class="p-street-address">123 Main st.</div>
<span class="p-locality">Los Angeles</span>,
<abbr class="p-region" title="California">CA</abbr>,
<span class="p-postal-code">91316</span>
<div class="p-country-name">U.S.A</div>
<time class="dt-bday">1951-05-26</time> birthday
<div class="p-category">physicist</div>
<div class="p-note">First American woman in space.</div>
</div>
Core properties:
p-name
- The full/formatted name of the person or organizationp-honorific-prefix
- e.g. Mrs., Mr. or Dr.p-given-name
- given (often first) namep-additional-name
- other (e.g. middle) namep-family-name
- family (often last) namep-sort-string
- string to sort byp-honorific-suffix
- e.g. Ph.D, Esq.p-nickname
- nickname/alias/handleu-email
- email addressu-logo
- a logo representing the person or organization (e.g. a face icon)u-photo
- a photo of the person or organizationu-url
- home page or other URL representing the person or organizationu-uid
- universally unique identifier, preferably canonical URLp-category
- category/tagp-adr
- postal address, optionally embed an h-adrMain article: h-adrp-post-office-box
- post office box description if anyp-extended-address
- apartment/suite/room name/number if anyp-street-address
- street number + namep-locality
- city/town/villagep-region
- state/county/provincep-postal-code
- postal code, e.g. US ZIPp-country-name
- country namep-label
p-geo
oru-geo
, optionally embed an h-geoMain article: h-geop-latitude
- decimal latitudep-longitude
- decimal longitudep-altitude
- decimal altitudep-tel
- telephone numberp-note
- additional notesdt-bday
- birth dateu-key
- cryptographic public key e.g. SSH or GPGp-org
- affiliated organization, optionally embed an h-cardp-job-title
- job title, previously 'title' in hCard, disambiguated.p-role
- description of roleu-impp
per RFC4770, new in vCard4 (RFC 6350)p-sex
- biological sex, new in vCard4 (RFC 6350)p-gender-identity
- gender identity, new in vCard4 (RFC 6350)dt-anniversary
Experimental properties currently in use in the wild but not (yet) part of the official h-card spec.
u-sound
- sound file containing the proper pronunciation of the name property, per vCard (RFC 6350).- Used by Martijn van der Ven with a clip of his given name.
- Needs a GitHub issue to track.
Status
h-card is a microformats.org draft specification. Public discussion on h-card takes place on the #microformats channel on irc.freenode.net (view recent discussions), and specific issues may be filed on GitHub.
h-card is ready to use and implemented in the wild. For backwards compatibility you should also mark up top-level h-cards as classic hCards.
Property Details
(stub, to be expanded)
p-adr
p-adr
can optionally embed an h-adr to cluster associated structured address properties. E.g. adding "p-adr" to the example earlier:
<div class="h-card">
<p class="p-name">Joe Bloggs</p>
<p class="p-adr h-adr">
<span class="p-street-address">17 Austerstræti</span>
<span class="p-locality">Reykjavík</span>
<span class="p-country-name">Iceland</span>
</p>
</div>
Q: Why would you use "p-adr" to cluster associated structured address properties?
A: Because if you have more than one structured address, clustering which properties go with which address keeps them deterministically together, instead of depending on array indices or other heuristics.
p-tel
Note: use of 'value' within 'p-tel' should be automatically handled by the support of the value-class-pattern. And for now, the former hCard '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).
dt-bday
Using truncated representations of dates for birth date is often good practice as noted in the vcard spec eg
1985-04
for April 19851985
for the year 1985--04-12
for April 12th with no specified year
Reserved properties
The following properties were supported by the legacy hCard format, but were not carried over to h-card due to lack of real-world usage, or other problems. They are not part of h-card and should not be published, consumed, or proposed.
p-organization-name
p-organization-unit
p-tz
— timezone offsetit's going to be a hard one to "get right", as the way timezones work in vcard/ical is very weird, and timezones as a whole are an iffy thing to denote (quite the disconnect between complexity, automated processing ability, actually representing what a user would want to show/display or already does on their homepage, and actually representing something useful to parse and do something with)
there's certainly no ecosystem of publishers & consumers supporting p-tz in any meaningful interoperable way
— tantek in #microformats
dt-rev
Examples in the wild
See also: h-card Examples on indieweb.org
Real world in the wild examples of sites and services that publish or consume h-card:
- ... add uses of h-card you see in the wild here.
- Security Jobs London uses h-card with legacy hCard fallback markup (to satisfy Google's Structured Data Testing Tool) in the footer of each page
- Brett Comnes marks up his posts with h-card (example)
- Ben Werdmuller marks up his homepage and posts with h-card example)
- Joel Purra uses a hidden h-card with legacy hCard fallback markup (to satisfy Google's Structured Data Testing Tool) on the front page
- Laurent Eschenauer marks his homepage profile up using h-card
- Tom Morris marks himself up with h-card as well as venues he’s checked into (example)
- W3Conf 2013 uses h-card for all the event 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 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 on his home page as well as within h-entrys on permalink pages to indicate authorship.
- Barnaby Walters uses h-card on his home page, as well as within h-entries for notes and articles, both to indicate authorship and also when mentioning people within the body of the notes.
- microformats.org at 7 years presentation with and h-card markup for people and organizations.
- Rise of the Indie Web hCards (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has microformats2 h-card markup
- WebMaker by Mozilla has microformats2 h-card on event search (e.g. search near Portland Oregon) and event pages (e.g. IndieWebCamp 2012).[1]
- WebFWD by Mozilla has microformats2 h-card markup on experts and team pages
- IndieWebCamp has microformats2 h-event markup with embedded h-cards for the organizers and the location.
- Mozilla Events page has microformats2 h-event markup with attendees marked up with h-card.
- Tristan Thomas uses h-card on his home page
- Cold32.com uses h-card (and h-geo) on its about-the-author-and-contact page
- Workfrom.co renders h-cards for venues (e.g. [2])
- PCWDLD.com renders h-cards for download pages(e.g. Download page example)
offline
- spreadly marks up share permalink pages with minimal h-cards inside h-entry
- App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 (example)
- Sandeep Shetty marks his homepage and posts up with h-card and h-entry (example)
Validating
- indiewebify.me h-card validator parses h-card markup and makes suggestions for things to add, with code samples
Test and validate microformats2 markup in general with:
- https://pin13.net/mf2/ - enter your markup directly
- https://pin13.net/ - enter a URL to a page to test where it says "Microformats Parser"
Implementations
Software implementations that publish or consume h-card, including themes, plugins, or extensions:
(This section is a stub that needs expansion! In practice, nearly every CMS on every indie web site supports publishing h-card by default, and most sites which support receiving webmentions parse h-card for authorship data.)
When adding an implementation, please provide and link to its home page and open source repo if any.
- GNUsocial source code
- Hubzilla source code
- Friendica source code
- InkBlot
- Aperture consumes h-card to show authorship information of feed posts (source code)
- XRay consumes h-card and flattens it into a more minimal format (source code)
- Known publishes and consumes h-card to show authorship of posts and responses
- Bridgy publishes microformats-2 versions of siloed content (including h-card for authorship) for consumption by mf2-consumers
- webmention.io consumes h-card for authorship data of incoming webmentions which it accepts on behalf of other sites
- ...
- ...
Backward Compatibility
Publisher Compatibility
For backward compatibility, you may wish to use classic hCard classnames in addition to the more future-proof h-card properties, for example:
<p class="h-card vcard">
<span class="p-name fn">Joe Bloggs</span>,
<span class="p-org org">Awesome Nonprofit</span>
...
</p>
The class vcard
is a backward compatible root class name that indicates the presence of an hCard.
fn, org, and all the other backward compatibility hCard property class names are listed below.
Parser Compatibility
Microformats parsers SHOULD detect classic properties only if a classic root class name is found and parse them as microformats2 properties.
If an "h-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-
Background
This work is based on the existing hCard and vcard specifications.
Design Principles
(stub, expand)
Additions
We've tried very hard with h-card to stay compatible with the vCard4 vocabulary, and thus additions should be proposed on the vCard4 mailing list.
However, you may still use this wiki to capture additions for h-card here: