h-entry

From IndieWeb
h-entry icon
h-entry icon

h-entry is the microformats2 vocabulary for marking up blog posts on web sites. It can also be used to mark-up any other episodic or time series based content.

Why

Why publish

Adding h-entry markup to your homepage and permalinks is the simplest way to make those pages easily readable by consuming code like indieweb readers.

Adding h-entry to your post pages enables post information discovery on your permalinks, which is useful for a variety of things, including:

  • reply context syndication
  • syndication of your replies from your site as comments on the permalinks of the sites that you reply to.

Adding h-entry to your home page enables:

  • subscribing to your posts directly from your home page (no separate feed needed).
  • A building block for adding PuSH 0.4 support for real time subscribers of your updates

Any page with an explicit author and publication date can use h-entry and enables:

Why consume

By using a microformats2 parser, and looking for h-entry items, your code will automatically get both h-entry and classic hAtom post information from people's post pages and home pages, which are published in total in combination by a double digit percentage of the web (thanks to WordPress default templates including such markup for 5+ years), and especially cutting edge IndieWeb sites.

HTML on a page is historically more accurate than feed files (see that page for more details on why).

Thus for the best user experience, your consuming code should first consume the h-entry (and by backward compat of such parsers, hAtom) of pages before looking at secondary side files.

How to

How to publish

Use h-entry to markup:

A list of possible properties can be found on the microformats wiki.

h-entries will typically be used in two places: alone on post permalink pages and in plural on feed pages.

On post permalink pages the h-entry should be the top-level microformat (not nested under anything).

For feed pages with multiple h-entrys, if you would like to omit the author property on the individual h-entrys on the page, you can wrap them in an h-feed and put the author info on the h-feed. This will allow the author information to be discovered by the authorship algorithm.

How to consume h-entry

For how to consume feeds of multiple h-entry posts, see How To Consume Feeds.

To consume a single h-entry:

  • look for the first h-entry on the page. If none are found, this page does not represent a post.

For each h-entry, regardless of whether they’re being treated as a single post or part of a feed:

  • to find the author of the h-entry, use the authorship algorithm
  • to determine how to display the post as a comment, use the comment presentation algorithm
  • to determine the published datetime:
    • if the h-entry has a published or updated property which is a valid datetime
      • if the datetime is floating (i.e. has no timezone), use the implied timezone heuristic to determine the timezone
    • if the fixed published datetime is in the future, cap it to the present
      • you may wish to preserve the source timezone in the derived time, and optionally also allow a small window within which β€œfuture” posts are accepted e.g. 10 minutes
    • if there was no datetime, let the published datetime of the post be the datetime it was first seen

When notified of an update to a h-entry, either by webmention or PuSH or any other plumbing:

  • optionally archive current status of
  • update the updated property to be the updated date of the post using the same datetime resolving process given above
  • re-apply the above per-h-entry algorithm, ignoring any updates to the published

See also the processes documented on comment for handling incoming comments, updates and deletions.

Issues

move general processing

Many of the processes documented on comment (e.g. deletion) can be applied equally to other cases of h-entry consumption (e.g. in a reader), and some of the detail given here applies to comments processing (e.g. datetime processing). Anything which is applicable to general h-entry processing should be moved here, leaving only anything specific to the comment use-case on comment, and these algorithm referred to from there --Barnaby Walters 05:33, 9 June 2014 (PDT)

bad hentry properties

Some h-entrys encountered are missing a "content" property and have just the implied "p-name" property which end up with an inappropriate value for the name. These URLs were sent via pingback to a blog post on aaronparecki.com, and are hEntry posts rather than the microformats2 version.

  • …add issues with h-entry consumption to be resolved here.

IndieWeb Examples

Pretty much everyone on the IndieWeb publishes h-entry because it is a fundamental building block for the richer UX of Webmentions of federating and displaying comments, and showing higher fidelity reply-contexts on reply pages as well.

E.g. see people's personal sites linked from chat-names.

What uses it

Numerous projects and sites are parsing and consuming h-entry for various purposes, including:

In short, h-entry is the key building block for the indieweb. It represents a unit of content, to be syndicated, for a variety of use-cases.

Requests

Requests to add h-entry support. Both publishing and consuming code.

Requested consuming code

See Also

  • http://microformats.org/wiki/h-entry
  • microformats2
  • in-reply-to
  • datetime
  • to do: file issue to figure out a mechanism (property & protocol?) to handle explicitly expression of the explicit audience for a post. Use-case: exporting of mixed public / protected / private posts into a single h-feed, where each post expresses its audience, so that when imported, the destination can replicate the expected privacy. May be applicable to any vocab.
  • ^ real world example of lack of this kind of support potentially causing a problem: relevant to Twitter exports/imports: https://indieweb.social/@philhawksworth/109353365961680480
    • "If like me and many others, you're in the process of moving your tweets to a new home on your own site, a word of caution:Tweets to twitter circles are not labelled as such in the export, so be aware of the risk of making public what you might have intended for a trusted group" @philhawksworth November 16, 2022