====== XML Syndication ======

[[DokuWiki]] makes some of its data available as XML feed through the [[this>feed.php]] file. The feed can be subscribed in a [[wp>Aggregator|newsreader]].

The XML Syndication feature was implemented by using the excellent [[http://www.bitfolge.de/rsscreator-en.html|Feed Creator Class]] by Kai Blankenhorn.

===== Config Options =====

How the feed is produced can be configured through certain config options. When the feed.php is called without any arguments it will use these options to create the feed. All options can also be overriden by parameters passed in the URL.


==== Links ====

Each item in the created feed will have a link, this option specifies where this link points to.

  * **Config Option:** [[config#rss_linkto]]
  * **URL Parameter:** linkto
  * **Default:** diff
  * **Possible Values:**

^ Value   ^ Link Target ^
| page    | the revison of the of the page when the feed was created |
| current | the most current revision of the page |
| rev     | the revison view of the page |
| diff    | a [[diff]] view of the page changes |

==== Feed Content ====

What is shown in the item bodies of the feed is controlled by this option.

  * **Config Option:** [[config#rss_content]]
  * **URL Parameter:** content
  * **Default:** abstract
  * **Possible Values:**

^ Value    ^ Item Content ^
| abstract | The first paragraph of a page |
| diff     | a plain text diff of the page changes  |
| htmldiff | a HTML formatted diff table of the page changes  |
| html     | the full HTML rendered page content |

==== Feed Format ====

DokuWiki can create XML feeds in multiple formats.

  * **Config Option:** [[config#rss_type]]
  * **URL Parameter:** type
  * **Default:** rss1
  * **Possible Values:**

^ Value  ^ Feed Format ^
| rss    | RSS 0.91 |
| rss1   | RSS 1.0  |
| rss2   | RSS 2.0  |
| atom   | ATOM 0.3 |
| atom1  | ATOM 1.0 |

==== List Mode ====

The feed.php can be used to export a list of recent changes (default) but can be used for other lists as well.

  * **Config Option:** none
  * **URL Parameter:** mode
  * **Default:** recent
  * **Possible Values:**

^ Value   ^ List Mode ^
| recent  | list most recent pages with the newest on top |
| list    | simply list all pages of a namespace (see below for selecting which one)  |
| search  | list pages matching a certain search query given through an additional parameter ''q'' |

==== Namespace Filter ====

The feed can be limited to include pages of a certain namespace only.

  * **Config Option:** none
  * **URL Parameter:** ns
  * **Default:** *
  * **Possible Values:** any valid namespace

==== Item Limits ====

The number of pages listed in the feed can be controlled as well.

  * **Config Option:** [[config#recent]]
  * **URL Parameter:** num
  * **Default:** 20
  * **Possible Values:** any integer

==== Including Minor Edits ====

By default no minor edits will be shown in the feed. This can be changed by an URL argument.

  * **Config Option:** none
  * **URL Parameter:** minor
  * **Default:** 0
  * **Possible Values:** 0 or 1

==== Caching  ====

XML feeds are cached to reduce the load on the wiki. This option controls how long feed caches are valid.

  * **Config Option:** [[config#rss_update]]
  * **URL Parameter:** none
  * **Default:** 5*60
  * **Possible Values:** time in seconds

==== Summaries ====

The [[summary]] of a page change will usually be included in the feed item title. This might be unwanted sometimes and can be disabled.

  * **Config Option:** [[config#rss_show_summary]]
  * **URL Parameter:** none
  * **Default:** 1
  * **Possible Values:** 0 or 1

===== Examples =====

  * [[this>feed.php?type=rss2&num=5]] returns a [[http://backend.userland.com/rss|RSS 2.0]] feed of the 5 most recent changes
  * [[this>feed.php?mode=list&type=atom&linkto=page&ns=wiki]] list all pages in the wiki namespace as an [[http://intertwingly.net/wiki/pie/FrontPage|ATOM 0.3]] feed with all items linking to the page directly

==== Summary of URL parameters and Options ====

  * General syntax for RSS links from your own installation :

  [[this>feed.php?URL_parameter1=Value_X&URL_parameter2=Value_X......&URL_parameterN=Value_X]]

| **Name :**| [[syndication#Links]] | [[syndication#Feed Content]] | [[syndication#Feed Format]] | [[syndication#List Mode]] | [[syndication#List Mode]] | [[syndication#Namespace Filter]] | [[syndication#Item Limits]] | [[syndication#Including Minor Edits]] | 
^//URL Parameter: //^  linkto=  ^  &content=  ^  &rss_type=  ^  &mode=  ^  &q=  ^  &ns=  ^  &num=  ^  &minor=  ^
^//Default Value :// :|  diff  |  abstract  |  rss1  |  recent  |  Any name  |  *  |  20  |  0  |
^//Value 2// :|  current  |  diff  |  rss  |  list  |    |  Any Name  |  any integer  |  1  |
^//Value 3// :|  rev  |  htmldiff  |  rss2  |  search  |  -  |  -  |  -  |  -  |
^//Value 4// :|  page  |  html  |  atom  |    -  |  -  |  -  |  -  |  -  |
^//Value 5// :|  -  |  -  |  atom1  |    -  |  -  |  -  |  -  |  -  |


===== Feeds and ACLs =====

When ACLs are enabled, read restricted pages will **not** be included in public feeds.

If you want to access feeds for restricted pages you have to pass your username and password along in the URL like this: %%''http://example.com/dokuwiki/feed.php?u=username&p=password''%%.

:!: This is not very secure and might lead to the leakage of your user credentials. When DokuWiki is running atop of ''mod_php'' passing login credentials via HTTP Basic Auth as supported by some newsreaders might work as well.

===== See also =====

  * [[wiki:features:rss|RSS/ATOM Feed Aggregation]] for adding external feeds to your DokuWiki pages
  * The [[plugin:feed|feed plugin]] for more ways to export your [[plugin:blog]] posts via RSS
  * Tips on [[wiki:tips:blogging#feed_setup|feed setup]] when blogging with DokuWiki