====== 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 [[https://www.hd-digitalmarketing.de/rsscreator-webdesign/|Feed Creator Class]] FIXME by Kai Blankenhorn.

===== Config/URL Options =====

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

==== Disabling ====

Default the XML feed of DokuWiki is available, but you can disable it via the disable actions configuration.

  * **Config Option:** [[config:disableactions]]
  * **Default:** XML Syndication (RSS) unchecked

==== 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 revision of the page when the feed was created |
| current | the most current revision of the page |
| rev     | the revision 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 |

==== Content Type ====

Control whether media is included in the list of feed items.

  * **Config Option:** [[config:rss_media]]
  * **URL Parameter:** view
  * **Default:** both
  * **Possible Values:** both, pages, media

^ Value    ^ Item Content ^
| both     | list pages and media |
| pages    | list only pages, do not list media  |
| media    | list only media, do not list pages  |

==== 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 ====

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 changelog entries with the newest on top (this corresponds to the wiki's [[recent_changes]] page) |
| 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

In [[#list mode]] ''list'', the feed will contain pages from the given namespace only, no sub namespaces.

In [[#list mode]] ''recent'', sub namespaces are included.

Namespace limitation is not directly supported for the [[#list mode]] ''search''. Instead you can give a namespace limitation in the query (using the ''@'' syntax) -- this however **will** include sub namespaces.

==== Item Sorting ====
The sorting of pages listed in the feed can be changed ([[#list mode]] ''list'' only)

  * **Config Option:** none
  * **URL Parameter:** sort
  * **Default:** natural
  * **Possible Values:** date, natural

Affects only the [[#list mode]] ''list''. Natural sorting is just the order of the stored pages.

In [[#list mode]] ''recent'', the pages are always ordered by date, as its name already suggests.

==== Item Limits ====

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

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

Note: The actual number of items returned in the feed will also be limited by the number of items that meet the criteria of the feed.

==== 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

==== Show New Items only ====

Allows to output newly created items only.

  * **Config Option:** none
  * **URL Parameter:** only_new
  * **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 =====

  * ''%%http://example.com/dokuwiki/feed.php?type=rss2&num=5%%'' returns a [[wikipedia>RSS|RSS 2.0]] feed of the 5 most recent changes
  * ''%%http://example.com/dokuwiki/feed.php?mode=list&type=atom&linkto=page&ns=wiki%%'' lists all pages in the namespace "wiki" as an [[wikipedia>Atom (standard)|ATOM 0.3]] feed with all items linking to the page directly

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

==== Approach with .htusers ====

For my configuration (dokuwiki 2008-05-05 and [[http://liferea.sourceforge.net/|Liferea]]) the HTTP Basic Auth approach did not work out of the box. It seems that the authentication was not happening because the web server did not ask for it. So I forced this by creating a .htusers file (out of the dokuwiki user information) and restrict the access to feed.php:

I used the following simple script to generate a htusers file (used by apache) out of dokuwikis user data:

  user@host# cat <<EOF > update_htusers
  #!/bin/sh
  grep -v '^#' users.auth.php |  cut -sd\: -f1,2 > .htusers
  EOF
  user@host# chmod +x update_htusers
  user@host# ./update_htusers
  

Add to your existing .htaccess in dokuwiki main folder:

<code apache>
AuthType Basic
AuthName "feed"
AuthUserFile path-to-your-htusers-file
<Files feed.php>
  Order deny,allow
  require valid-user
</Files>
</code>

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

  * [[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 [[tips:blogging#feed_setup|feed setup]] when blogging with DokuWiki
  * The [[plugin:Feedauth]] plugin sends an "authorization required" header in the feed, for some clients needed.