Difference between revisions of "h-entry"

From Microformats Wiki
Jump to navigation Jump to search
(→‎Backward Compatibility: add compat faq with What about rel bookmark)
(→‎What about rel bookmark: note rel typically document scoped, and rel=bookmark special casing is not particularly author-friendly for understanding rel values in general)
Line 142: Line 142:
  
 
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=bookmark was the old [[hAtom]] way of marking up permalinks. Since then two factors have contributed to reducing use of rel inside microformats:
* rel is always 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.
+
* 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.
 
* 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.
 +
 +
<nowiki>*</nowiki> even though rel=bookmark in particular is article-element / sectioning scoped in HTML5[http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-bookmark], 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 ==
 
== Background ==

Revision as of 21:45, 15 August 2013

<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 0.1.

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-10-01, 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">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 specification to learn more about property classnames.

Properties

h-entry properties, inside an element with class h-entry:

  • 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 - unique entry ID
  • p-geo - geophysical location the entry was posted from, optionally embed h-geo
    Main article: h-geo
  • p-latitude - decimal latitude
  • p-longitude - decimal longitude
  • p-altitude - decimal altitude

The following experimental properties are in use in the wild but are not yet part of the spec:

  • u-in-reply-to - the URL which the h-entry is considered a reply to or comment on.
    • Potentially optionally an embedded (or nested?) h-entry (for reply contexts) but I’m the only one doing that right now so not considered a recommendation --bw 16:44, 13 June 2013 (UTC)
  • p-comment - optionally embedded (or nested?) h-entry(ies), each of which is a comment on/reply to the parent h-entry. See Brainstorming for a Comment Microformat.

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)

  • u-photo
  • 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-issues, the #microformats #microformats on freenode 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 0.1 entries.

Property Details

(stub, to be expanded)

hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) SHOULD prefer p-name over p-entry-title, and use p-entry-title value(s) as a fallback if there is no p-name.

FAQ

  • 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 the p-summary.
  • ...

Examples in the wild

Real world in the wild examples:


Main article: microformats validators

Test and validate microformats2 markup in general with:

Backward Compatibility

Publisher Compatibility

For backward compatibility, you may wish to use classic hAtom 0.1 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 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
  • geo - parse as p-geo h-geo including compat root geo
  • latitude
  • longitude

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:

  • rel by typically* document scoped in Microformats 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 principles of start as simple as possible, 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 0.1 microformat, and extensive selfdogfooding in the indie web camp community.

Design Principles

(stub, expand)

See Also