Extension:WikiArticleFeeds

The WikiArticleFeeds Extension is a MediaWiki extension for converting regular wiki articles into RSS and Atom feeds.

Installation

 * 1) Download the files from SVN and place them under $IP/extensions/WikiArticleFeeds
 * 2) Add   into your wiki's LocalSettings.php
 * 3) Installation can be verified through Special:Version

Configuration (optional)
If you'd like to disable the default link interpretation behavior (see the example), you can do so by adding this to your LocalSettings.php:

Usage
Once installed, editors of your wiki may begin feeding pages immediately, no further system configuration is required.

The extension registers three tags:
 * &lt;startFeed&gt; (Required) - Denotes the beginning of an article segment containing feed data.
 * &lt;endFeed&gt; (Required) - Denotes the end of a feed data segment.
 * &lt;feedBurner&gt; (Optional) - Specifies that FeedBurner is to serve the feed, rather than publishing it directly.

If an article contains a feed section, links titled 'RSS' and 'Atom' will appear in the Toolbox. Additionally, because the appropriate &lt;meta&gt; tags are supplied, your browser may show a feed icon in the address bar.

Note: In the Monobook skin, the Toolbox is in the left-hand sidebar column, towards the bottom.

As mentioned before, a feed section is delimited by the &lt;startFeed /&gt; and &lt;endFeed /&gt; flags. Note that these are CLOSED tags, and are functionally equivalent to &lt;startFeed&gt;&lt;/startFeed&gt; and &lt;endFeed&gt;&lt;/endFeed&gt;</tt> respectively.

The &lt;feedBurner&gt;</tt> tag, when specified, MUST HAVE a single attribute called 'name'. This is the final URL component of the feedburner.com feed URL.

For example, consider this url: http://jimbojw.com/wiki/index.php?title=Blog

The Atom feed URL for this page would be: http://jimbojw.com/wiki/index.php?title=Blog&action=feed

Suppose this has been mapped via feedburner.com to: http://feeds.feedburner.com/Jimbojwcom-Blog

And thus, the following is added to the original article text to complete the circle: <feedBurner name="Jimbojwcom-Blog" />

Note that using FeedBurner in this fashion does not prevent users from still trying to access the generated feeds directly, but it does change all the links to point to feedburner rather than back to the wiki.

Example
<startFeed />

Description of my feed.

Second Feed Item
Brand New! I just made a new Item!

--Anon 10:12, 8 December 2006 (MST)

First Feed Item
Here is the content for my first item ever.

--Anon 08:42, 4 December 2006 (MST)

<endFeed />

The description for the rendered RSS or Atom feed will be "Description of my feed." The feed will have two items, both authored by "User:Anon</tt>".

To add a new item, simply add a new wiki section between the startFeed and endFeed delimiters. Continuing the previous example:

<startFeed />

Description of my feed.

Third Item
When you get a chance, please check out the Main Page.

--~

Second Feed Item
Brand New! I just made a new Item!

--Anon 10:12, 8 December 2006 (MST)

First Feed Item
Here is the content for my first item ever.

--Anon 08:42, 4 December 2006 (MST)

<endFeed />

Feed item publication dates are determined automatically from standard wiki signatures, so in the above's "Third Item", the "-- ~ </tt>" results in a format which WikiArticleFeeds can parse (as in the first and second items).

Finally, the generated feed item URLs will be links to the matching page section, unless a link is made in the feed item text. In the above, the first two items would link to " </tt>" and "  </tt>", while the third would link to " Main Page </tt>".

Tagging and Filtering
As of version 0.6, WikiArticleFeeds supports tagging by way of either the &lt;itemTags&gt;</tt> tag or  </tt> parser function.

To tag a feed item, insert either the &lt;itemTags&gt;</tt> tag, or the a call to the  </tt> parser function somewhere between the opening header of the item (== Item Title ==</tt>) and the header of the next item.

For example, to mark an item about dogs and cats, you could do any of the following: <itemTags>dogs, cats</itemTags>

Tagging an item does nothing to the finished page itself other than add an HTML comment indicating the tag. Also, it will not affect the feed directly as this does not inject real actual RSS or Atom categories.

However, once you've tagged items, you can filter a feed by the item tags. For example consider the following URL: http://jimbojw.com/wiki/index.php?title=Blog&action=feed

This will generate a feed from the page called Blog, containing all items therein. Now consider this variant: http://jimbojw.com/wiki/index.php?title=Blog&action=feed&tags=mediawiki

This will also generate a feed, but it will only contain items which have been tagged as 'mediawiki' articles.

Extended Example
For an article to be considered a feed, it must have at least one feed section.

To delimit a section use the &lt;startFeed /&gt; and &lt;endFeed /&gt;</tt> tags respectively. These tags are merely flags, and any attributes specified, or content inside the tags themselves will be ignored.

For example, the following segment contains two feed items. &lt;startFeed /&gt;

More Rain
Nope. Today it was rainy, again. Blah.

Not Sunny Today
Not quite rainy, just foggy, maybe it'll get better?

&lt;endFeed /&gt;

Note that the choice of level-3 heading (' === </tt>') is purely coincidental. Any normal heading depth is acceptable - from '<tt> = </tt>' (1) to '<tt> ====== </tt>' (6) as long as they're consistent within the feed block.

Mixed Level Headings
Having a mix of level headings is ok, but only the sections highest level heading (lowest number) will be considered feed items.

For example, the following is perfectly legitimate: &lt;startFeed /&gt;

More Rain
Nope. Today it was rainy, again. Blah.

This is not a new Item
This text and the preceding heading both belong to the "More Rain" item.

Not Sunny Today
Not quite rainy, just foggy, maybe it'll get better?

&lt;endFeed /&gt;

Attribution
To give credit to the author of an item, the only thing that's required is a single instance of the default signature - "<tt> ~ </tt>". This will be converted by MediaWiki at submit-time into the fully expanded user name and date of submission.

WikiArticleFeeds is smart enough to know that if it sees such a construct, it should treat this as a declaration of the Author and Date.

Although attribution is certainly not required, you are strongly recommended to follow this convention. Externally, it aids the reader of the feed by providing more meta-data about the item. Internally, it permits aggregation to operate more smoothly (see next section).

Aggregation
WikiArticleFeeds can combine or aggregate feeds. For example, consider the following wiki markup: &lt;startFeed /&gt;

More Rain
Nope. Today it was rainy, again. Blah.

--Anon 08:42, 4 December 2006 (MST)

&lt;endFeed /&gt;

...

&lt;startFeed /&gt;

Not Sunny Today
Not quite rainy, just foggy, maybe it'll get better?

--Anon 09:56, 3 December 2006 (MST)

&lt;endFeed /&gt;

When this page is converted into a single feed, both the "Not Sunny Today" and "More Rain" items will appear, in reverse chronological order (newest first).

Although this particular use case may not seem too exciting, it does permit the pulling together of feeds on separate pages via MediaWiki Template notation (also sometimes referred to as Transclusion).

For example, consider the following three articles:

&lt;startFeed /&gt;
 * Rainy Feed

More Rain
Nope. Today it was rainy, again. Blah.

--Anon 08:42, 4 December 2006 (MST)

Not Sunny Today
Not quite rainy, just foggy, maybe it'll get better?

--Anon 09:56, 3 December 2006 (MST)

&lt;endFeed /&gt;

&lt;startFeed /&gt;
 * Sunshiny Feed

More Sunshiny
Just another beautiful day.

--Anon 06:37, 18 August 2006 (MST)

Hoping for more Sun
Hope it's nice out tomorrow, too cloudy today ...

--Anon 10:08, 14 August 2006 (MST)

&lt;endFeed /&gt;


 * Aggregate Feed

Rainy Feed
Contents of the Rainy Feed:

Sunshiny Feed
Contents of the Sunshiny Feed ==

As you can imagine, rendering the article "Aggregate Feed" as an RSS or Atom feed will result in a combination of all items in both "Rainy Feed" and "Sunshiny Feed".

Automatic Linking
There are two options for automatically creating the feed's link URL. First, if there are no URLs, or the only URLs in the feed text itself are part of the attribution, then the feed URL will be simply a link to the item in the page.


 * Note: This behavior can be disabled by setting <tt>$wgForceArticleFeedSectionLinks</tt> to true in LocalSettings.php. See the installation section for details.

So for example, this feed's url:

Some Item
Some blog text.

--Anon 10:08, 14 August 2006 (MST) Would be equivalent to the wiki link "<tt> </tt>".

The other method of auto-linking is based on non-attribution links. The first non-attribution link found in the feed text becomes the feed item URL.

So this example:

Some Item
Checkout my new Main Page - it's great! (Oh, and while you're at it, check out the Announcements).

--Anon 10:08, 14 August 2006 (MST) Would be equivalent to the wiki link "<tt> Main Page </tt>".