h-entry

From Microformats Wiki
Jump to navigation Jump to search

h-entry is a simple, open format for episodic or datestamped content on the web. h-entry is often used with content intended to be syndicated, e.g. blog posts. h-entry is one of several open microformat standards suitable for embedding data in HTML.

h-entry is the microformats2 update to hAtom 0.1, in particular its "hentry" root class which itself was based on rfc-4287's "entry" element. For an update to "hfeed" see h-feed.

Status
This is a Living Specification yet mature enough to encourage additional implementations and feedback. This specification has portions that are stable, draft, and proposed. Features are stable unless explicitly labeled draft or proposed, or in draft or proposed sections. Draft and proposed features are likely to change substantively. While substantive changes to stable features are unexpected, it is a living specification subject to substantive change by issues and errata filed in response to implementation experience, requiring consensus among participating implementers as part of an explicit change control process.
Participate
Open Issues
Resolved issues before 2012-246
#microformats on freenode: #microformats on Freenode
Editor
Tantek Çelik
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 2020-08-25, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Example

Here is a simple blog post example: 

<article class="h-entry">
  <h1 class="p-name">Microformats are amazingh1>
  <p>Published by <a class="p-author h-card" href="http://example.com">W. Developera>
     on <time class="dt-published" datetime="2013-06-13 12:00:00">13<sup>thsup> June 2013time>p>
  
  <p class="p-summary">In which I extoll the virtues of using microformats.p>
  
  <div class="e-content">
    <p>Blah blah blahp>
  div>
article>

Parsed JSON: 

{
  "items": [
    {
      "type": [
        "h-entry"
      ],
      "properties": {
        "name": [
          "Microformats are amazing"
        ],
        "author": [
          {
            "value": "W. Developer",
            "type": [
              "h-card"
            ],
            "properties": {
              "name": [
                "W. Developer"
              ],
              "url": [
                "http://example.com"
              ]
            }
          }
        ],
        "published": [
          "2013-06-13 12:00:00"
        ],
        "summary": [
          "In which I extoll the virtues of using microformats."
        ],
        "content": [
          {
            "value": "Blah blah blah",
            "html": "
Blah blah blah
"
          }
        ]
      }
    }
  ]
}

Get started

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

p-name, p-author, dt-published and the other h-entry property classnames listed below define properties of the h-entry.

Note: The purpose of an entry is to place it around both the explicitly written content (in the content property or in other specific properties for non-textual content or responses) and whatever else is the context for that content, including properties for when it was published and/or updated, who created it, tags or categorization, and links to what the content is a response to (perhaps with a quoted excerpt) and/or links to syndicated copies.

Properties

h-entry properties, inside an element with class h-entry. All properties are optional and may be plural.

Core Properties

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

  • p-name - entry name/title
  • p-summary - short entry summary
  • e-content - full content of the entry
  • dt-published - when the entry was published
  • dt-updated - when the entry was updated
  • p-author - who wrote the entry, optionally embedded h-card(s)
  • p-category - entry categories/tags
  • u-url - entry permalink URL
  • u-uid - universally unique identifier, typically canonical entry URL
  • p-location - location the entry was posted from, optionally embed h-card, h-adr, or h-geo
  • u-syndication - URL(s) of syndicated copies of this post. The property equivalent of rel-syndication (example)
  • u-in-reply-to - the URL which the h-entry is considered reply to (i.e. doesn’t make sense without context, could show up in comment thread), optionally an embedded h-cite (reply-context) (example)
  • p-rsvp (enum, use element or Value Class Pattern)
    • "yes", "no", "maybe", "interested". Case-insensitive values, normalized to lowercase. Examples:
    • ... is going to ..., or
    • ... might go to ...
    • ... unable to go to ...
    • ... am interested/tracking/watching ...
  • u-like-of - the URL which the h-entry is considered a “like” (favorite, star) of. Optionally an embedded h-cite
  • u-repost-of - the URL which the h-entry is considered a “repost” of. Optionally an embedded h-cite.

Draft Properties

The following draft properties are in use in the wild (published and consumed), and are under strong consideration, but are not yet part of the core:

  • p-comment - optionally embedded (or nested?) h-cite(s), each of which is a comment on/reply to the parent h-entry. See Brainstorming for a Comment Microformat (example)
  • u-photo - one or more photos that is/are considered the primary content of the entry, unless there is a p-location h-card, which is still considered a "checkin" (i.e. with a photo). Otherwise the presence of a u-photo means the name of the entry should be interpreted as a caption on the photo, and the summary/content should be interpreted as a description of the photo.
  • u-video - special u- parsing rules for

Proposed Additions

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

The following interpretation is also proposed addition:

  • if the p-location is also an embedded h-card, the entry is treated as a "checkin".
    • -1 Aaronpk 14:22, 19 January 2017 (UTC) this post is not a checkin, but has an h-card as the p-location property.

Note: As h-entry usage grows to express and consume different kinds of content, we expect additional properties may be proposed and iterated as demonstrated by real-world needs, usage, and interoperability.

Proposing and upgrading

How do you add proposed properties and then upgrade them to draft and then core properties?

See: change control

Property Details

This section is a stub.

p-location

p-location has been re-used from h-event.

FAQ

p-name of a note

  • What is the p-name of a note?

venue an entry was posted from

  • How do you indicate a named venue where an entry was posted from? Like a restaurant or park.
    • Use an embedded h-card microformat on a p-location property value.

address an entry was posted from

  • How do you indicate the address where an entry was posted from? Like a restaurant or park.
    • If the address is just part of a named venue, see above, use an h-card
    • Otherwise use an embedded h-adr microformat on a p-location property value.

lat long an entry was posted from

  • How do you indicate the latitude and longitude of where an entry was posted from?
    • If the location has a name in addition to latitude and longitude, see above, use an h-card
    • Otherwise if there is an address in addition to latitude and longitude, see above, use an h-adr
    • Otherwise use an embedded h-geo microformat on a p-location property value.

dt-published property and HTML5 time element

  • Does the dt-published property need to be a time element?
    • The dt-published property should be a element so that you can take advantage of HTML5's "datetime" property.
    • This lets you specify a human-readable date in the value of the attribute, and the ISO8601 machine-readable date in the "datetime" property.

what is the bare minimum list of required properties on an h-entry

  • What is the bare minimum list of required properties on an h-entry?
    • No properties are explicitly required, but in practice a h-entry should have the following properties at a minimum for consumers:
  • url
  • published — if there is no "published" date for the "entry", then reconsider whether it is correct (or worth) marking it up as an entry.
  • What properties should an h-entry have in addition to the bare minimum?
    • Beyond the bare minimum, a typical h-entry should have the following as well:
  • content (or summary at least) - especially for structured content. For a plain text note, the content/summary (whichever is used) should be the same as the name, otherwise it will be implied from the text content of the root element.
  • name - for explicitly named/titled entries like blog posts and articles. Otherwise the entry is assumed to be a "title-less" note (like a tweet).
  • author - including a nested h-card with author details like name, photo, url.

Examples in the wild

Real world in the wild examples of sites and services that publish or consume h-entry:

  • ... add uses of h-entry you see in the wild here.
  • ind.ie mark up their blog listing and permalink pages with h-entry
  • 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 McAllen marks up his 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))
  • 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
  • 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
  • Okinawan-lyrics marks up his posts with h-entry and h-card (example)
  • App.net marks up profile pages and permalink pages with h-entry as of 2013-08-06 (example)
  • The Twitter archive browser UI uses h-entry and h-card internally, unfortunately it’s not exposed as HTML in static files anywhere
  • 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)
  • Numerous newer W3C specs, e.g.
  • SemPress is a WordPress theme that supports h-card, h-feed/h-entry.
  • The Pastry Box Project use h-card and h-entry markup on their homepage and individual thoughts pages
  • Aaron Parecki uses h-entry to mark up notes, e.g. 2012/230/reply/1.
  • Tantek Çelik uses 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
  • Barnaby Walters uses h-entry on all notes and articles, as well as nested within notes as reply contexts example and comments example.

offline

  • spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

Validating

Main article: microformats validators

Test and validate microformats2 markup in general with:

Implementations

Software implementations that publish or consume h-entry, 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-entry by default.)

When adding an implementation, please provide and link to its home page and open source repo if any.

Backward Compatibility

Publisher Compatibility

For backward compatibility with legacy hAtom 0.1 consuming implementations, use hAtom 0.1 classnames (or rel values) in addition to the more future-proof h-entry properties, for example: 

<article class="h-entry hentry">
  <h1 class="p-name entry-title">A Tale Of Two Tagsh1>
  <address class="p-author author h-card vcard">
    <a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandraa>
  address>
  <time class="dt-published published" datetime="2012-06-20T08:34:46-07:00">June 20, 2012time>
  <div class="e-content entry-content">
    <p>It was the best of visible tags, it was the alternative invisible tags.p>
    <p>The a tag is perhaps the best of HTML, yet its corresponding invisible link tag has uses too.p>
  div>
  <a href="/category/uncategorized/" rel="category tag" class="p-category">Generala>
article>
ℹ️ Note: Note: you may use any valid HTML5 elements. The article h1 address time elements are used in the example as semantically richer suggestions, however in general div span work fine too. The time element is special though in that its datetime attribute provides a more author/user friendly way of separating a machine readable ISO8601 datetime from a human readable summary.

The list of equivalent hAtom 0.1 classnames and rel values is provided 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-entry" is found, don't look for an "hentry" on the same element.

Compat root class name: hentry
Properties: (parsed as p- plain text unless otherwise specified):

  • entry-title - parse as p-name
  • entry-summary - parse as p-summary
  • entry-content - parse as e-content
  • published - parse as dt-
  • updated - parse as dt-
  • author - including compat root vcard in the absence of h-card
  • category
  • rel=bookmark - parse as u-url. While not a class name nor typical microformats property, rel=bookmark was the only way to indicate an hentry permalink. Thus parsers should look for rel=bookmark hyperlinks inside an hentry, and take their "href" value as a value for a u-url property, including handling any relative URL resolution.
  • rel=tag - parse as p-category. While not a class name nor typical microformats property, rel=tag was the typical way to tag an hentry. Thus parsers should look for rel=tag hyperlinks inside an hentry, and take the last path segment of their "href" value as a value for a p-category property.

Proposed: (follow-up in issue #7)

  • time.entry-date[datetime] - in the absence of published, parse as dt-published. parse for the first element with class name of entry-date and non-empty datetime attribute inside an hentry, if there is no published property, use that time element's datetime attribute value for the dt-published property. Evidence: default WordPress themes 2011-2014([1][2][3][4]).
  • rel=author - in the absence of author, parse as u-author. While not a class name nor typical microformats property, rel=author was commonly used to link to an author's URL. Thus parsers should look for rel=author hyperlinks inside an hentry (or even on the same page, preceding the hentry), use the absolute version of it as a value for the u-author property if there is no "author" property. (citations to "hentry" examples in the wild that depend on rel=author needed to accepted this proposal. Note: default WordPress themes twentyeleven, twentytwelve, twentythirteen, twentyfourteen all use rel=author but only inside class="author vcard", and thus rel=author can be ignored since authorship is already picked up by existing author backcompat parsing.)

Compat FAQ

What about rel bookmark

Also asked as: Why use an h-entry u-url u-uid for permalinks when I have rel=bookmark?

A: tl;dr: use class="u-url u-uid" instead of rel=bookmark for post permalinks because it's simpler (fewer attributes), and works better across contexts (permalink page, recent posts on home page, collection of posts on archive pages).

rel=bookmark was the old hAtom 0.1 way of marking up permalinks. Since then two factors have contributed to reducing use of rel inside microformats: