h-feed

2016-11-30T13:30:33Z

Robinj: rm real world example - not an example anymore

<entry-title>h-feed</entry-title>

<dfn style="font-style:normal;font-weight:bold">h-feed</dfn> is a [[microformats2]] draft for marking up 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 the [[microformats2]] update to [[hAtom]]'s "hfeed".

{{cc0-owfa-license}}

== 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:
* '''<code>p-name</code>''' - name of the feed
* '''<code>p-author</code>''' - author of the feed, optionally embed an [[h-card]] {{main|h-card}}
* '''<code>u-url</code>''' - URL of the feed
* '''<code>u-photo</code>''' - 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:
* '''<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].

== Status ==
'''h-feed''' is a microformats.org draft specification. Public discussion on h-feed takes place on [[h-entry-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.

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

== Use Cases ==
* Named feeds
** IndieWeb Readers are consuming home page feeds marked up with h-feed and using the name of the h-feed in their user interfce.

* Generate an Atom feed
** This seems like a legacy use-case, not sufficient to actually justify h-feed.

* Feed per channel of content - needs a name
** "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'.

== 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 <html> element allows using p-name on the <title> 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 ==
=== Readers ===
* Shrewdness
* http://notenoughneon.com/feed.php

=== Proxies ===
* Bridgy

=== 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. ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing])

== Parsing ==
When parsing a page for an h-feed, do so per [[microformats2]].

Fallback:

If there is no explicit "h-feed" element, implementations may:
* Treat the <code><title></code> of the page or the URL of the page as the p-name
* Use http://indiewebcamp.com/authorship to discover authorship of posts.
* Treat top level [[h-entry]] elements as items in the feed.

== 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:
<source lang=html4strict>
<html class="h-feed">
…
<title class="p-name">sandeep.io</title>
…
</source>

=== 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 ==
* [[h-feed-issues]]
* [[h-entry]]
* [[microformats2]]
* [[hAtom]]

[[Category:Draft Specifications]]

Microformats Wiki - User contributions [en]

h-feed