This article describes the bare metal mechanics of a site or blog feed. Layers of abstraction have been piled upon what is actually a simple method for getting information out to the world. Here we uncover the original basics in creating a feed.
At the lowest level, a feed has two parts:
- Autodiscovery code in a HTML page.
- Feed information in a XML file.
Autodiscovery
Autodiscovery is code in a HTML page which tells browsers (or other software) that the site contains a feed. When visiting a site with autodiscovery, a browser indicates the presence of a feed on the site. For example, Firefox indicates a feed with an icon in the address bar:
Clicking on the feed icon will begin the subscription process for the site feed.
This behavior is triggered by an entry in the head section of the html page:
<link rel="alternate" type="application/atom+xml" href="http://2e5.com/feed/atom.xml" title="Atom Feed for 2e5.com">
There are 4 tags in this link specification:
- rel: Must specify "alternate".
- type: The MIME type of the feed. Usually "application/atom+xml" for atom feeds and "application/rss+xml" for rss feeds.
- href: Path to the feed XML file.
- title: Title for the feed.
The other half of feed creation is the feed XML file.
Feed XML
Feeds are usually Atom or RSS. I choose Atom because it is a more mature specification and can clearly indicate if content is Text or Html.Atom feed
The overall structure of an Atom feed looks like:
<?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> ... feed information ... ... feed entries ... </feed>
No surprises here. Just a plain vanilla Atom 1.0 xml package.
Feed Information Section
The feed information section gives information about the entire feed.
<updated>2011-01-11T14:30:02Z</updated>
<title type="text">2e5.com</title>
<subtitle type="text">maker musings</subtitle>
<link rel="self" type="application/atom+xml" href="http://2e5.com/feed/atom.xml"/>
<link rel="alternate" type="text/html" hreflang="en" href="http://2e5.com/"/>
<id>urn:uuid:219b0366-844a-473b-a1b0-dcfc4a7b0e29</id>
<icon>feedIcon.jpg</icon>
<logo>feedLogo.jpg</logo>
<rights>© 2011 Bill Ola Rasmussen</rights>
<author>
<name>Bill Ola Rasmussen</name>
<email>billra@gmail.com</email>
<uri>http://2e5.com/</uri>
</author>
Lots of information about the feed can be specified here. Most interesting entries are:
- updated: indicates the last time the feed was updated. This date must conform to RFC 3339.
- id: is a permanent, universally unique identifier for the feed. If the feed changes locations this id must stay the same. Some suggest that this id be built using some processing of the site url. I must poliely disagree. I recommend that you use a generated UUID.
- icon: should be an image with a 1:1 aspect ratio. When shown it is usually with a small size.
- logo: should be an image with a 2:1 (wide) aspect ratio.
The Atom Syndication Format is described in RFC 4287. Read this to understand all Atom feed fields.
One or more feed entries follow the feed information section.
Feed Entries
Here is a typical feed entry:
<entry>
<updated>2011-01-11T16:30:02Z</updated>
<title>Volkite</title>
<category term="kite"/>
<link href="http://2e5.com/kite/volkite/" />
<id>urn:uuid:39670cdc-ed32-45bc-9154-ee7ee4acd37a</id>
<summary>Volkite, a new design</summary>
<content type="html">
<img class="rbox" src="http://2e5.com/kite/volkite/IMG_3368_left_front_1s.jpg" width="400" height="765" alt="Volkite front left view">
<p>
Volkite is a kite with two skin foil construction on the leading edge and single
skin for the rest of the canopy. It is lighter and uses less material than a standard
parafoil.
<p>
<ul><li> Flat aspect ratio: 3
</li><li> Area: 1.5 m<sup>2</sup>
</li><li> Tip to Tip: 212 cm
</li><li> Chord: 70.5 cm
</li></ul>
The LE has 14 cells comprised of 7 mini-ribs and 6 full ribs.
The mini-ribs stop short of the point where the lower and upper skin
meet, allowing for air passage between adjoining cells. This also helps
to avoid the pucker distortion which can occur when a rib narrows to join
two skins.
<p>
Working with a (partially) single skinned kite is illuminating because it clearly shows
when a section of canopy is not not contributing to lift.
<p>
<a href="http://2e5.com/kite/volkite/">Read More at 2e5.com</a>
</content>
</entry>
The same comments about updated and id entries made in the feed information section also apply to this feed entry section.
The snippet of html in this feed was taken directly from an article published on the website. In order to "advertise" this article, a section of the article is extracted and put into the content section of the feed, with a "click here for the full article" link at the bottom.
If you look closely at this html, you may notice something interesting: The content looks like html, but all "<" have been replaced by "<"! XML uses "<" for its own structuring purposes, so html inside of the XML formatted Atom feed requires this substitution.
Another aspect of this snippet is that the images now have absolute references. In the article, the images were specified with a plain "imageName.png" indicating that the image was in the same directory as the html file. In the example above, the full path is specified: "http://2e5.com/kite/volkite/IMG_3368_left_front_1s.jpg". This is done because we have no fixed current location reference from which to create a path to the image.
Finally, notice the css style specification: class="rbox". This is actually ignored in the feed, as there is no header to reference the style sheet definition. To maintain the original look and feel, the css style information needs to be folded back in to the html using an inline style converter.
Complete Atom Feed Example
Putting it all together:
<?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <updated>2011-01-11T14:30:02Z</updated> <title type="text">2e5.com</title> <subtitle type="text">maker musings</subtitle> <link rel="self" type="application/atom+xml" href="http://2e5.com/feed/atom.xml"/> <link rel="alternate" type="text/html" hreflang="en" href="http://2e5.com/"/> <id>urn:uuid:219b0366-844a-473b-a1b0-dcfc4a7b0e29</id> <icon>feedIcon.jpg</icon> <logo>feedLogo.jpg</logo> <rights>© 2011 Bill Ola Rasmussen</rights> <author> <name>Bill Ola Rasmussen</name> <email>billra@gmail.com</email> <uri>http://2e5.com/</uri> </author> <entry> <updated>2011-01-11T16:30:02Z</updated> <title>Volkite</title> <category term="kite"/> <link href="http://2e5.com/kite/volkite/" /> <id>urn:uuid:39670cdc-ed32-45bc-9154-ee7ee4acd37a</id> <summary>Volkite, a new design</summary> <content type="html"> <img class="rbox" src="http://2e5.com/kite/volkite/IMG_3368_left_front_1s.jpg" width="400" height="765" alt="Volkite front left view"> <p> Volkite is a kite with two skin foil construction on the leading edge and single skin for the rest of the canopy. It is lighter and uses less material than a standard parafoil. <p> <ul><li> Flat aspect ratio: 3 </li><li> Area: 1.5 m<sup>2</sup> </li><li> Tip to Tip: 212 cm </li><li> Chord: 70.5 cm </li></ul> The LE has 14 cells comprised of 7 mini-ribs and 6 full ribs. The mini-ribs stop short of the point where the lower and upper skin meet, allowing for air passage between adjoining cells. This also helps to avoid the pucker distortion which can occur when a rib narrows to join two skins. <p> Working with a (partially) single skinned kite is illuminating because it clearly shows when a section of canopy is not not contributing to lift. <p> <a href="http://2e5.com/kite/volkite/">Read More at 2e5.com</a> </content> </entry> </feed>
The feed above shows only one entry. Any number of entries can be included in the feed. New entries are inserted just under the feed information section.
End Notes
It is a very good idea to check your feed using the W3C Feed Validation Service after every update.The Mozilla foundation has made some freely available feed icons which can be used to link to a feed on your site. On this page, this icon is used in the following html:
<a type="application/atom+xml" href="atom.xml"> <img src="feed-icon-28x28.png" width="28" height="28" alt="2e5.com Atom Feed" ></a>
I use the following procedure for making a new entry in the 2e5.com Atom feed:
- Copy an existing feed entry to a position just under the feed information section.
- Generate a new UUID for this entry.
- Use the current time for the updated sections in both the feed information section and this new entry.
- Update the title, summary, etc. sections in the new entry.
- Replace the content section of the new entry. (see below)
The content section of a new entry is some html from an article with a link to the article so an interested reader get more information. To prepare the html for use in the content section of the entry, I use the following procedure:
- Convert the article page from html + css to html with inline formatting using an inline style converter.
- Trim the processed article down to the length for a feed entry and add a link to the article.
- Find any relatively referenced items (images, etc.) and replace the reference with an absolute path.
- Replace all all "<" with "<".
That's all there is to incorporating a feed into your site. Creating feed entries by hand is not difficult, and knowledge of exactly how things work makes troubleshooting site feed problems much easier.
![[Valid Atom 1.0]](valid-atom.png "Validate my Atom 1.0 feed"){kind=small}