doc/tips/switching_to_usedirs.mdwn

   1 [[!meta date="2007-04-29 22:48:35 +0000"]]
   2
   3 As of version 2.0, ikiwiki will switch to enabling the 'usedirs' setting by
   4 default. This *will* break all URLs to wikis that did not have 'usedirs'
   5 turned on before. You can either follow this procedure to convert your wiki
   6 to usedirs, or edit your setup file and turn usedirs back off.
   7
   8 * Upgrade ikiwiki to 2.0.
   9 * Force ikiwiki to rebuild your wiki, by using `ikiwiki-mass-rebuild`,
  10   or manually.
  11 * Since usedirs is enabled, ikiwiki will have created a bunch of new
  12   html files. Where before ikiwiki generated a `dest/foo.html`, now it will
  13   generate `dest/foo/index.html`. The old html files will be removed.
  14 * If you have a blog that is aggregated on a Planet or similar, all the
  15   items in the RSS or atom feed will seem like new posts, since their URLs
  16   have changed. See [[howto_avoid_flooding_aggregators]] for a workaround.
  17 * Now all the URLs to pages in your wiki have changed. See
  18   [[redirections_for_usedirs]] for instructions on setting up redirections
  19   to keep the old URLs working.
  20
  21 Why usedirs?
  22 ------------
  23 There are several advantages to `usedirs`, including simpler URLs, URLs that
  24 aren't dependent on the underlying implementation (`.html`), and being able to
  25 use URLs as tags as described in the [rel-tag
  26 microformat](http://microformats.org/wiki/rel-tag).
  27
  28 The main disadvantage is that it is harder to browse using `file://` URIs,
  29 since `file:///dir/` doesn't automatically translate to `dir/index.html`. This
  30 is something one could fix in the browser though.