h-entry: Difference between revisions
(→Properties: Added u-syndication experimental property with example, clarifed what it means to be in use in the wild) |
(→Properties: added aaronpk example for u-photo) |
||
Line 53: | Line 53: | ||
* '''<code>u-repost-of</code>''' - the URL which the h-entry is considered a “repost” of. Optionally an embedded [[h-cite]]. | * '''<code>u-repost-of</code>''' - the URL which the h-entry is considered a “repost” of. Optionally an embedded [[h-cite]]. | ||
The following properties are proposed additions based on various existing link preview markup conventions which are ''not'' yet used in the wild (Related: [[link-preview-brainstorming]]) | The following properties are proposed additions based on various existing link preview markup conventions which are ''not'' yet commonly used in the wild (Related: [[link-preview-brainstorming]]) | ||
* '''<code>u-photo</code>''' - a representative photo or image for the entry, e.g. primary photo for an article or subject-cropped photo, suitable for use in a [[link-preview]]. | * '''<code>u-photo</code>''' - a representative photo or image for the entry, e.g. primary photo for an article or subject-cropped photo, suitable for use in a [[link-preview]] ([http://aaronparecki.com/notes/2014/03/12/3/devsummit example]) | ||
* '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code> | * '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code> | ||
* '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code> | * '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code> |
Revision as of 15:49, 13 March 2014
<entry-title>h-entry</entry-title> Tantek Çelik (Editor)
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 draft standards suitable for embedding data in HTML/HTML5.
h-entry is the microformats2 update to hAtom's "hentry". For an update to "hfeed" see h-feed.
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-10-31, 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 amazing</h1>
<p>Published by <a class="p-author h-card" href="http://example.com">W. Developer</a>
on <time class="dt-published" datetime="2013-06-13 12:00:00">13<sup>th</sup> June 2013</time>
<p class="p-summary">In which I extoll the virtues of using microformats.</p>
<div class="e-content">
<p>Blah blah blah</p>
</div>
</article>
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.
See microformats2-parsing to learn more about property classnames.
Properties
h-entry properties, inside an element with class h-entry:
p-name
- entry name/titlep-summary
- short entry summarye-content
- full content of the entrydt-published
- when the entry was publisheddt-updated
- when the entry was updatedp-author
- who wrote the entry, optionally embedded h-card(s)p-category
- entry categories/tagsu-url
- entry permalink URLu-uid
- unique entry IDp-location
- location the entry was posted from, optionally embed h-card, h-adr, or h-geo
The following experimental properties are in use in the wild (published and consumed) but are not yet part of the spec:
p-comment
- optionally embedded (or nested?) h-cite(s), each of which is a comment on/reply to the parent h-entry. See comment-brainstorming (example)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)u-like-of
- the URL which the h-entry is considered a “like” (favorite, star) of. Optionally an embedded h-cite (example)u-repost-of
- the URL which the h-entry is considered a “repost” of. Optionally an embedded h-cite.
The following properties are proposed additions based on various existing link preview markup conventions which are not yet commonly used in the wild (Related: link-preview-brainstorming)
u-photo
- a representative photo or image for the entry, e.g. primary photo for an article or subject-cropped photo, suitable for use in a link-preview (example)u-audio
- consider special u- parsing rules for<audio>
u-video
- consider special u- parsing rules for<video>
All properties are optional.
Status
h-entry is a microformats.org draft specification. Public discussion on h-entry takes place on h-entry-feedback, the #microformats irc channel on irc.freenode.net, and microformats-new mailing list.
h-entry is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-entries up as classic hAtom entries.
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?- 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.
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.
- Use an embedded h-card microformat on a
address an entry was posted from
lat long an entry was posted from
- How do you indicate the latitude and longitude of where an entry was posted from?
does the dt-published property need to be a time element
- The
dt-published
property should be a<time>
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
Examples in the wild
Real world in the wild examples:
- ... add uses of h-entry you see in the wild here.
- 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)
- spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-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.
Validating
- indiewebify.me h-entry validator parses h-entry markup, finds common errors 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"
Backward Compatibility
Publisher Compatibility
For backward compatibility, you may wish to use classic hAtom classnames in addition to the more future-proof h-entry properties, for example:
<div class="h-entry hentry">
<h1 class="p-name entry-title">My great blog post</h1>
</div>
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 asp-name
entry-summary
- parse asp-summary
entry-content
- parse ase-content
published
- parse as dt-updated
- parse as dt-author
- including compat rootvcard
in the absence ofh-card
category
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 way of marking up permalinks. Since then two factors have contributed to reducing use of rel inside microformats:
- rel by typically* document scoped in HTML5 - thus making it inappropriate for use in microformats that are aggregated, e.g. a collection of posts on a home page or in monthly archives.
- it is easier to always use class names for properties. When formats use two (or more!) attributes in HTML to specify properties, confusion results in lower data quality (of the markup and thus the stuff that is marked up). Thus per the microformats principle of simplicity, in microformats2 we only use class names for properties.
* even though rel=bookmark in particular is article-element / sectioning scoped in HTML5[1], it's a detail that typical authors are not going to remember, and thus it's not good to depend on it for any kind of format.
Background
This work is based on the existing hAtom microformat, and extensive selfdogfooding in the indie web camp community.
Design Principles
(stub, expand)