hcard-authoring

hCard authoring

This page contains useful tips and guidelines for how to author hCards, either from scratch, or by adding markup to existing content.

Goal: The goal of this document is to provide some good intuitive guidelines that should make it as easy and as quick as possible for any web author to create hCards or add hCard markup to existing content.

Audience: Web authors and designers. This document is written for easy consumption and understanding by any web designer who knows at least enough (X)HTML and CSS to use HTML class names on elements and write CSS selectors that apply styles to those class names. Please help with clarifying/simplifying this document accordingly.

Author(s): Tantek Çelik

Creating new hCards

Start with the hCard creator, and for additional fields and properties (e.g. telephone numbers, instant messaging contacts), see the hCard examples page.

Adding hCard markup to existing content

Natural language hCard

See Adactio: Journal - Natural language hCard.

Minimal Markup Changes

The important thing to keep in mind when adding hCard to existing content, is the fact that hCard was designed so that it could be added with minimal (most often no) changes to the existing presentation of the page. Thus keep this in mind: change as little markup as possible. If you want to fix various pages to be valid XHTML etc., that's fine.

In all cases below, where it says to add an element with class name of "xyz", if you can find an existing element that precisely surrounds the necessary content, then re-use that element and simply add the class name "xyz" to it (by adding it to the class attribute on the existing element, or by adding a new class attribute class="xyz" to elements without a class attribute).

Find People or Organizations

Start with looking for all mentions of people or organizations on a page. All of those are potential hCards. Even more so if they are linked to their respective URLs (e.g. home pages / blogs).

If a person (or organization, henceforth shortened to just "person/org") is mentioned several times on a page, consider marking up the mention which is the most detailed, definitive, or otherwise thorough as an hCard. Ideally you might want to mark up all instances of a person/org as hCards, but for now, just keep it simple and markup the most representative instance. (Perhaps the most "definitive" instance, which could also then be marked up with a <dfn> element around the name of the person/org for additional semantic XHTML goodness.)

Determine The Surrounding Element for Each

For each person/org that you want to turn into an hCard, find the smallest element that contains all the info about that person/org, and no info about any other person/org.

Add the class name "vcard" to that element.

If there is no such element (perhaps the nearest enclosing element contains more than one person/org), then add a <span class="vcard">...</span> or <div class="vcard">...</div> that wraps the info about about that person/org and just that person/org.

The rest of the markup for this hCard MUST go inside that element with the class name "vcard".

The Importance of Names

The name is the one required property of hCard. Thus be sure to mark up the name of the person with the class name "fn". For names of people which are two simple words (text separated by space) and where the first word is their given name and the second word is their family name, the class name "fn" is sufficient. E.g.

<div class="vcard"><span class="fn">Rohit Khare</span></div>

For people with middle names (e.g. "Håkon Wium Lie"), or with multi-word last names (e.g. "Thomas Vander Wal"), you must mark them up with the "n" property and its sub-properties "given-name" and "family-name", e.g.:

<div class="vcard"><span class="fn n" lang="no">
 <span class="given-name">Håkon</span> 
 <span class="additional-name">Wium</span>
 <span class="family-name">Lie</span>
</span></div>

<div class="vcard"><span class="fn n">
 <span class="given-name">Thomas</span> 
 <span class="family-name">Vander Wal</span>
</span></div>

For organizations, be sure to put both the "fn" and "org" class names on the same element. Having those be the same is the hint to hCard consumers that the hCard represents an organization rather than a person. E.g.

<div class="vcard"><span class="fn org">Technorati</span></div>

Representative URLs

One of the most common patterns for person/orgs in web content is the name of the person/org, hyperlinked to their definitive/preferred web site.

Blogrolls are a good example of this (see also XOXO).

Since the class attribute takes a space separated set of class names, one can often markup the URL on the same element as the name, e.g.

<span class="vcard"><a href="http://theryanking.com" class="fn url">Ryan King</a></span>

Titles

If the person's job title is mentioned, mark it up with <span class="title">...</span>.

Though typical vCards/hCards have only a single job title, if someone has several job titles listed say in a comma delimited list, just markup the whole lot of them with one big <span class="title">...</span>.

View source on the W3C Technical Plenary Agenda for examples of people with multiple titles.

Other affiliations

As vCard seems to imply a model of a person only being associated with one organization (at least certainly that's how most vcard-implementations appear to be written), consider placing other affiliations and info about the person into <span class="title">...</span> elements. You can have more than one; converters will simply append them all in source order.

View source on the W3C Technical Plenary Agenda for examples of people with additional affiliations (such as W3C Working Groups) marked up inside "note" elements.

Sometimes text in a document near a person/contact will explain *why* that person should be contacted. Such information is also useful to have in a "note" element.

View source on the O'Reilly ETech 2006 invite for examples of people with additional "For ... " reasons marked up as "note" elements.

Set the lang when different

In an English language document (lang="en"), be sure to markup the element surrounding any non-English names of people, companies, titles, notes etc. with a lang attribute with the appropriate value.

E.g. Spanish names in an english document should be marked up with (lang="es") on their elements.

View source on the W3C Technical Plenary Agenda, specifically Ignacio Marín, for an example of a person and org marked up with a lang attribute.

Phone Numbers

Add a few phone numbers like this:

	<div class="tel">
	  <span class="type">work</span>
	  tel:<span class="value">1-250-555-2142</span>
	</div>

	<div class="tel">
	  <span class="type">work</span>
	  toll free:<span class="value">1-800-555-1855</span>
	</div>
	<div class="tel">
	  <span class="type">work</span>
	  <span class="type">fax</span>
	  fax:<span class="value">1-250-555-2135</span>
	</div>

Geographic Coordinates

Add your geographic coordinates:

      <span class="geo">
	<span class="latitude">48.430092246</span>
	<span class="longitude">-123.364348450</span>
      </span>

More tips and guidelines

Feel free to add more tips that experience has taught you while marking up hCards, even if all you add is a brief catch phrase that reminds you.

• How to note some text, so you can make a comment like who your admin assistant is.
• How to mark up TYPE in phone numbers. Is that done correctly above?
• More inline code examples, perhaps one for each section (suggestion from Cdevroe)
• (suggestion from brian) you mention blogroll, this might be out of scope, but you could mention that XFN and hCard can be interweaved - it is not one or the other
• ...

Related Pages

• hCard
• hCard cheatsheet - hCard properties
• hCard creator (feedback) - create your own hCard.
• hCard authoring - learn how to add hCard markup to your existing contact info.
• hCard examples - example usage of various classes within hCard.
• hCard examples in the wild - an on-going list of websites which use hCards.
• hcard-supporting-user-profiles - sites with user profiles marked up with hCard - a very common example.
• hCard FAQ - if you have any questions about hCard, check here.
• hCard implementations - websites or tools which either generate or parse hCards.
• hCard parsing - normative details of how to parse hCards.
• hCards and pages - semantic distinctions between different hCards on a page, and how to identify each
• hcard-user-interface - techniques and issues surrounding user-interfaces to author, publish, and display hCards.
• hCard profile - the XMDP profile for hCard
• hCard singular properties - an explanation of the list of singular properties in hCard.
• hCard tests - a wiki page with actual embedded hCards to try parsing.
• hCard advocacy - encourage others to use hCard
• hCard "to do" - jobs to do

The hCard specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. These thoughts, issues, and questions are kept in separate pages.

• hCard brainstorming - brainstorms and other explorations relating to hCard.
  • hcard-parsing-brainstorming - brainstorming specific to parsing of hCard
  • geo brainstorming
• hCard feedback - general feedback (as opposed to specific issues).
• hCard issues - specific issues with the specification.
• vCard errata - corrections to the vCard specification, which underlies hCard.
• vCard suggestions - suggested improvements to the vCard specification.