h-feed: Difference between revisions
Jump to navigation
Jump to search
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 (talk | contribs) No edit summary |
(→Parser Compatibility: incorporate more specific backcompat parsing wording, some from h-entry, and provide clear fallback from h-feed to hfeed to implied h-feed of top level h-entrys) |
||
| (16 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
<entry-title>h-feed</entry-title> | |||
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span> | |||
---- | |||
<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. | |||
h-feed is the [[microformats2]] update to [[hAtom]], and in particular its "hfeed" root class. | |||
{{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 === | |||
* [https://github.com/kylewm/woodwind Woodwind] | |||
* [https://github.com/barnabywalters/shrewdness Shrewdness] | |||
* http://notenoughneon.com/feed.php (404 as of 2017-05-29) | |||
=== Proxies === | |||
* Bridgy | |||
=== Converters === | |||
* '''[http://unmung.com unmung]''' - will transform an RSS or Atom feed into an [[h-feed]] containing h-entries, | |||
* '''[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]) | |||
== Backward Compatibility == | |||
=== Publisher Compatibility === | |||
(this section is a stub and needs to be expanded with real world examples and minimal properties) | |||
=== Parser Compatibility === | |||
For backward compatibility with existing [[hatom|hAtom]] content, 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: <code id="hfeed">hfeed</code><br/> | |||
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) | |||
* <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. | |||
* <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]).] | |||
* <code>site-description</code> - parse as '''<code>p-summary</code>''' [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. | |||
* <code><title></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 == | |||
=== 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]] | |||
Revision as of 00:27, 16 September 2017
<entry-title>h-feed</entry-title>
Tantek Çelik (Editor)
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.
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-04-24, 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 feedp-author- author of the feed, optionally embed an h-cardMain article: h-cardu-url- URL of the feedu-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.
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 explicitly 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
- Woodwind
- Shrewdness
- http://notenoughneon.com/feed.php (404 as of 2017-05-29)
Proxies
- Bridgy
Converters
- unmung - will transform an RSS or Atom feed into an h-feed containing h-entries,
- microformats to RSS - a Yahoo! pipe that converts a URL containing an h-feed containing h-entries, into an RSS feed. (2013-10-21 blog post announcing)
Backward Compatibility
Publisher Compatibility
(this section is a stub and needs to be expanded with real world examples and minimal properties)
Parser Compatibility
For backward compatibility with existing hAtom content, 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 asp-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 ap-categoryproperty.site-title- parse asp-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 asp-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 asp-name- https://indieweb.org/authorship on the page to discover default authorship for any h-entry posts lacking explicit parsed
authorproperties.
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">sandeep.io</title>
…
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