h-feed: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(add Implementations section with converters. hmm, maybe time to upgrade this to a draft spec)
m (s/<source>/<syntaxhighlight>/)
(37 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{stub}}
<dfn style="font-style:normal;font-weight:bold">h-feed</dfn> is a simple, open format for publishing a stream or feed of [[h-entry]] posts, like complete posts on a home page or archive pages, or summaries or other brief lists of posts. h-feed is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.


'''<dfn>h-feed</dfn>''' is a [[microformats2]] experiment with a top level feed object to contain [[h-entry]] posts.
h-feed is the [[microformats2]] update to [[hAtom]], and in particular its "hfeed" root class.


From experience with [[hAtom]], it's not clear that there's actually a need (use-case) for a top level feed, but for those that wish to experiment with it, here it is.
;<span id="status">Status</span>
:'''h-feed''' is a microformats.org draft specification.
:h-feed is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-feed up as a classic [[hAtom]] "hfeed".
 
;<span id="participate">Participate</span>
:[https://github.com/microformats/h-feed/issues Open Issues]
:[[IRC]]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
: {{cc0-owfa-license}}
__TOC__
 
== Properties ==
h-feed properties, inside an element with class '''h-feed'''. All properties are optional.


root class name: h-feed
root class name: h-feed


properties:
=== Core Properties ===
* p-name - name of the feed
The following ''core'' h-feed properties have broad consensus:
* p-author - author of the feed, optionally embed an [[h-card]] {{main|h-card}}
* '''<code>p-name</code>''' - name of the feed
* u-url - URL of the feed
* '''<code>p-author</code>''' - author of the feed, optionally embed an [[h-card]] {{main|h-card}}
* u-photo - representative photo / icon for the feed
* '''<code>u-url</code>''' - URL of the feed
* '''<code>u-photo</code>''' - representative photo / icon for the feed


children:
children:
* nested [[h-entry]] objects representing the items of the feed
* nested [[h-entry]] objects representing the items of the feed


== Use Cases ==
=== Draft Properties ===
* Generate an Atom feed
None currently.
** This seems like a legacy use-case, not sufficient to actually justify h-feed.
 
=== Proposed Properties ===
The following properties are proposed additions based on various observed examples in the wild, but are awaiting at least one reader / real world consuming code example to become a draft property:
* '''<code>p-summary</code>''' - based on non-trivial actual content usage of "atom:subtitle" on Blogger and WordPress.com featured blogs's Atom feeds.
* '''<code>p-entry</code>''' - to be more consistent with the cascading of p-author or [http://microformats.org/wiki/comment-brainstorming#Proposal p-comment].
 
== Proposed Additions ==
 
* Proposal that h-feed not be limited to h-entry, due use cases for feeds of h-cards or h-events https://github.com/microformats/h-feed/issues/3
* Proposal to add implied h-feed in cases where no h-feed is explicitly marked up. https://github.com/microformats/h-feed/issues/1
 
== Discovery ==
Implementations may discover one or more h-feeds in several ways.
 
* If the implementation is given a URL (e.g. from a user entering it) to do h-feed discovery, it:
** SHOULD do traditional feed discovery by looking through link elements with a rel value of "alternate"
** For each link alternate with a media type of <code>[https://indieweb.org/text/mf2%2Bhtml text/mf2+html]</code>
**# get its href,
**# do any relative-URL resolution needed on that href to construct an absolute URL
**# fetch that absolute URL and [[microformats2-parsing|parse it]] (within a specific element matching a fragment in the URL if any) for microformats2 items,
**# look for top-level items (within that fragment element subtree if any) of type "h-feed"
** ALSO implementations MAY [[microformats2-parsing|parse the whole document]] and look in its top level items for those of type "h-feed"


* Feed per channel of content - needs a name
* If the implementation has already parsed an HTML document, it may look for elements with a class name of "h-feed"
** "I will have a feed per tag (channel) so I want to name them." - Sandeep Shetty in #indiewebcamp
 
** It appears there is some desire to create separate feeds for an indieweb site for separate subsets of content, and name them <em>explicitly</em> accordingly. This presents a need for a container object for the h-entry elements, where the container itself can have a name. This is a potential interesting use-case for an explicit 'h-feed'.
Details:
* Implementations may fetch public h-feeds without having to pass cookies or any other user-identifying information
* Implementations should parse h-feed documents without executing any scripts (parse as if scripting is disabled or unimplemented)
* If an implementation needs only one h-feed, it should take the first one found per the above methods
 
=== Implied h-feed ===
In the absence of an explicit "h-feed" element, implementations may infer an h-feed of all top level microformats items in the document (as determined by [[microformats2-parsing]] the document). Among those top level items, if precisely one of them is an "h-card" then it is used to imply a "p-author h-card" property of the implied "h-feed" and is removed from the "children" array of the implied "h-feed".
 
E.g. if an archive page has a collection of h-entry elements at the top level, implementations may imply an h-feed container for all of them and treat the entire document as a feed.


== Examples in the wild ==
== Examples in the wild ==
Add any examples in the wild that you find to the top of this list.
* ...
* http://sandeep.io/ uses h-feed with p-name and p-author properties and child h-entry posts. In particular using h-feed on the &lt;html&gt; element allows using p-name on the &lt;title&gt; element and re-using the visible window title of the HTML page as the name of the feed, neatly avoiding a [[DRY]] violation.
* http://tantek.com/ uses h-feed with p-name and p-author properties and child h-entry posts.


== Implementations ==
See https://indieweb.org/h-feed#IndieWeb_Examples for examples of h-feed in the wild.
=== Converters ===
 
* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed
== Consumers ==
 
See https://indieweb.org/h-feed#Consumers_of_H-Feed for examples of implementations that consume h-feed.
 
== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[hAtom]] classnames in addition to the more future-proof h-feed properties, for example:
 
<syntaxhighlight lang="html">
<div class="h-feed hfeed">
  <h1 class="p-name site-title">The Markup Blog</h1>
  <p class="p-summary site-description">Stories of elements of their attributes.</p>
 
  <article class="h-entry hentry">
    <a class="u-url" rel="bookmark" href="2020/06/22/balanced-divisive-complementary">
      <h2 class="p-name entry-title">A Tale Of Two Tags: Part 2</h2>
    </a>
    <address class="p-author author h-card vcard">
      <a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandra</a>
    </address>
    <time class="dt-published published" datetime="2012-06-22T09:45:57-07:00">June 21, 2012</time>
    <div class="p-summary entry-summary">
      <p>From balanced harmony, to divisive misunderstandings, to complementary roles.</p>
    </div>
    <a href="/category/uncategorized/" rel="category tag" class="p-category">General</a>
  </article>
 
  <article class="h-entry hentry">
    <a class="u-url" rel="bookmark" href="2020/06/20/best-visible-alternative-invisible">
      <h2 class="p-name entry-title">A Tale Of Two Tags: Part 1</h2>
    </a>
    <address class="p-author author h-card vcard">
      <a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandra</a>
    </address>
    <time class="dt-published published" datetime="2012-06-20T08:34:46-07:00">June 20, 2012</time>
    <div class="p-summary entry-summary">
      <p>It was the best of visible tags, it was the alternative invisible tags.</p>
    </div>
    <a href="/category/uncategorized/" rel="category tag" class="p-category">General</a>
  </article>
 
</div>
</syntaxhighlight>
 
{{note|Note: you may use any valid HTML5 elements. The <code>article h1 h2 address time</code> elements are used in the example as semantically richer suggestions, however in general <code>div span</code> work fine too. The <code>time</code> element is special though in that its <code>datetime</code> attribute provides a more author/user friendly way of separating a machine readable ISO8601 datetime from a human readable summary.
}}
 
The class '''<code>hfeed</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[hAtom]] feed.
 
Backward compatibility hAtom property class names and rel values are listed 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-feed" is found, don't look for an "hfeed" on the same element.


== Parsing ==
Compat root class name: <code id="hfeed">hfeed</code><br/>
When parsing a page for an h-feed, do so per [[microformats2]].
Properties: (parsed as '''p-''' plain text unless otherwise specified):


Fallback:
(this section is a stub and needs review and citations to note what real world examples would each of these backcompat parsing rules actually help parse)


If there is no explicit "h-feed" element, implementations may:
* <code>rel=tag</code> - parse as '''<code>p-category</code>'''. While not a class name nor typical microformats property, rel=tag was the defined way to tag an hfeed. Thus parsers should look for rel=tag hyperlinks inside an hfeed, and take the last path segment of their "href" value as a value for a '''<code>p-category</code>''' property.
* Treat the <code>&lt;title&gt;</code> of the page or the URL of the page as the p-name
* <code>site-title</code> - parse as '''<code>p-name</code>''' [WordPress (Core? Typical themes?) has this class name by default, and without it buggy parsers may imply p-name as the whole h-feed ([http://microformats.org/wiki/microformats2-parsing#parsing_for_implied_properties implied properties only apply to actual h-x roots, not backcompat]).]
* Use http://indiewebcamp.com/authorship to discover authorship of posts.
* <code>site-description</code> - parse as '''<code>p-summary</code>''' [WordPress (Core? Typical themes?) has this class name by default]
* Treat top level [[h-entry]] elements as items in the feed.
 
If no "h-feed" nor "hfeed" element is found, however multiple top-level [[h-entry]] elements (explicit or backcompat) are found, implementations may use:
* top level [[h-entry]] elements as items in a synthetic h-feed.
* <code>&lt;title&gt;</code> of the page or the URL of the page as '''<code>p-name</code>'''
* https://indieweb.org/authorship on the page to discover default authorship for any h-entry posts lacking explicit parsed <code>author</code> properties.


== FAQ ==
== FAQ ==
Line 49: Line 147:


If you want re-use the &lt;title&gt; of your page as the name of your feed, you can do so by putting the h-feed root class name on the &lt;html&gt; element, and the p-name property class name on the &lt;title&gt; element, e.g. here's a snippet showing how those tags would look:
If you want re-use the &lt;title&gt; of your page as the name of your feed, you can do so by putting the h-feed root class name on the &lt;html&gt; element, and the p-name property class name on the &lt;title&gt; element, e.g. here's a snippet showing how those tags would look:
<source lang=html4strict>
 
<syntaxhighlight lang="html">
<html class="h-feed">
<html class="h-feed">
   …  
   …  
   <title class="p-name">sandeep.io</title>
   <title class="p-name">The Markup Blog</title>
   …
   …
</source>
</syntaxhighlight>
 
Real world example:
* Sandeep Shetty has marked up his home page, http://sandeep.io/ in this way.
 
 
=== What should a subscriber do with a page with multiple feeds ===
''What do I do when a user subscribes to a URL with multiple distinct h-feeds?''
 
A feed reader should subscribe to the first h-feed it finds at a URL.
 
Related: http://indiewebcamp.com/reader


== See Also ==
== See Also ==
Line 71: Line 159:
* [[microformats2]]
* [[microformats2]]
* [[hAtom]]
* [[hAtom]]
[[Category:Draft Specifications]]

Revision as of 21:19, 26 July 2023

h-feed is a simple, open format for publishing a stream or feed of h-entry posts, like complete posts on a home page or archive pages, or summaries or other brief lists of posts. h-feed is one of several open microformat draft standards suitable for embedding data in HTML.

h-feed is the microformats2 update to hAtom, and in particular its "hfeed" root class.

Status
h-feed is a microformats.org draft specification.
h-feed is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-feed up as a classic hAtom "hfeed".
Participate
Open Issues
IRC
Editor
Tantek Çelik (Editor)
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 2024-10-31, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Properties

h-feed properties, inside an element with class h-feed. All properties are optional.

root class name: h-feed

Core Properties

The following core h-feed properties have broad consensus:

  • p-name - name of the feed
  • p-author - author of the feed, optionally embed an h-card
    Main article: h-card
  • u-url - URL of the feed
  • u-photo - representative photo / icon for the feed

children:

  • nested h-entry objects representing the items of the feed

Draft Properties

None currently.

Proposed Properties

The following properties are proposed additions based on various observed examples in the wild, but are awaiting at least one reader / real world consuming code example to become a draft property:

  • p-summary - based on non-trivial actual content usage of "atom:subtitle" on Blogger and WordPress.com featured blogs's Atom feeds.
  • p-entry - to be more consistent with the cascading of p-author or p-comment.

Proposed Additions

Discovery

Implementations may discover one or more h-feeds in several ways.

  • If the implementation is given a URL (e.g. from a user entering it) to do h-feed discovery, it:
    • SHOULD do traditional feed discovery by looking through link elements with a rel value of "alternate"
    • For each link alternate with a media type of text/mf2+html
      1. get its href,
      2. do any relative-URL resolution needed on that href to construct an absolute URL
      3. fetch that absolute URL and parse it (within a specific element matching a fragment in the URL if any) for microformats2 items,
      4. look for top-level items (within that fragment element subtree if any) of type "h-feed"
    • ALSO implementations MAY parse the whole document and look in its top level items for those of type "h-feed"
  • If the implementation has already parsed an HTML document, it may look for elements with a class name of "h-feed"

Details:

  • Implementations may fetch public h-feeds without having to pass cookies or any other user-identifying information
  • Implementations should parse h-feed documents without executing any scripts (parse as if scripting is disabled or unimplemented)
  • If an implementation needs only one h-feed, it should take the first one found per the above methods

Implied h-feed

In the absence of an explicit "h-feed" element, implementations may infer an h-feed of all top level microformats items in the document (as determined by microformats2-parsing the document). Among those top level items, if precisely one of them is an "h-card" then it is used to imply a "p-author h-card" property of the implied "h-feed" and is removed from the "children" array of the implied "h-feed".

E.g. if an archive page has a collection of h-entry elements at the top level, implementations may imply an h-feed container for all of them and treat the entire document as a feed.

Examples in the wild

See https://indieweb.org/h-feed#IndieWeb_Examples for examples of h-feed in the wild.

Consumers

See https://indieweb.org/h-feed#Consumers_of_H-Feed for examples of implementations that consume h-feed.

Backward Compatibility

Publisher Compatibility

For backward compatibility, you may wish to use classic hAtom classnames in addition to the more future-proof h-feed properties, for example:

<div class="h-feed hfeed">
  <h1 class="p-name site-title">The Markup Blog</h1>
  <p class="p-summary site-description">Stories of elements of their attributes.</p>

  <article class="h-entry hentry">
    <a class="u-url" rel="bookmark" href="2020/06/22/balanced-divisive-complementary">
      <h2 class="p-name entry-title">A Tale Of Two Tags: Part 2</h2>
    </a>
    <address class="p-author author h-card vcard">
      <a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandra</a>
    </address>
    <time class="dt-published published" datetime="2012-06-22T09:45:57-07:00">June 21, 2012</time>
    <div class="p-summary entry-summary">
      <p>From balanced harmony, to divisive misunderstandings, to complementary roles.</p>
    </div>
    <a href="/category/uncategorized/" rel="category tag" class="p-category">General</a>
  </article>

  <article class="h-entry hentry">
    <a class="u-url" rel="bookmark" href="2020/06/20/best-visible-alternative-invisible">
      <h2 class="p-name entry-title">A Tale Of Two Tags: Part 1</h2>
    </a>
    <address class="p-author author h-card vcard">
      <a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandra</a>
    </address>
    <time class="dt-published published" datetime="2012-06-20T08:34:46-07:00">June 20, 2012</time>
    <div class="p-summary entry-summary">
      <p>It was the best of visible tags, it was the alternative invisible tags.</p>
    </div>
    <a href="/category/uncategorized/" rel="category tag" class="p-category">General</a>
  </article>

</div>
ℹ️ Note: Note: you may use any valid HTML5 elements. The article h1 h2 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 class hfeed is a backward compatible root class name that indicates the presence of an hAtom feed.

Backward compatibility hAtom property class names and rel values are listed 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-feed" is found, don't look for an "hfeed" on the same element.

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

(this section is a stub and needs review and citations to note what real world examples would each of these backcompat parsing rules actually help parse)

  • rel=tag - parse as p-category. While not a class name nor typical microformats property, rel=tag was the defined way to tag an hfeed. Thus parsers should look for rel=tag hyperlinks inside an hfeed, and take the last path segment of their "href" value as a value for a p-category property.
  • site-title - parse as p-name [WordPress (Core? Typical themes?) has this class name by default, and without it buggy parsers may imply p-name as the whole h-feed (implied properties only apply to actual h-x roots, not backcompat).]
  • site-description - parse as p-summary [WordPress (Core? Typical themes?) has this class name by default]

If no "h-feed" nor "hfeed" element is found, however multiple top-level h-entry elements (explicit or backcompat) are found, implementations may use:

  • top level h-entry elements as items in a synthetic h-feed.
  • <title> of the page or the URL of the page as p-name
  • https://indieweb.org/authorship on the page to discover default authorship for any h-entry posts lacking explicit parsed author properties.

FAQ

How do I avoid duplicating the page title

I want to use the name (title) of my page as the name of my feed, how do I avoid duplicating the page title somewhere invisibly on the page as the feed name?

If you want re-use the <title> of your page as the name of your feed, you can do so by putting the h-feed root class name on the <html> element, and the p-name property class name on the <title> element, e.g. here's a snippet showing how those tags would look:

<html class="h-feed"><title class="p-name">The Markup Blog</title>

See Also