doc/tips/upgrade_to_3.0.mdwn

   1 Version 3.0 of ikiwiki makes some significant configuration changes, which
   2 you will need to deal with when upgrading from ikiwiki 2.x.
   3
   4 [[!toc ]]
   5
   6 # moving settings from Preferences page
   7
   8 The admin preferences page used to have settings for allowed attachments,
   9 locked pages, and banned users. These three settings have moved to the
  10 setup file:
  11
  12         allowed_attachments => "",
  13         locked_pages => "",
  14         banned_users => "",
  15
  16 If you have not yet upgraded to ikiwiki 3.0, you can look at the admin
  17 preferences page to see if any of these values is shown there, and copy
  18 them into the setup file.
  19
  20 ## setup file format change
  21
  22 The layout of the setup file changed in a significant way in version 2.60
  23 of ikiwiki. If you have not changed yours to the new format, now would be a
  24 good time to do so. Some new features, like the [[plugins/websetup]] interface,
  25 need the new format setup file.
  26
  27 You can convert old setup files into the new format by running
  28 `ikiwiki-transition setupformat your.setup`
  29
  30 ## prefix directives
  31
  32 In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has
  33 changed, requiring that the directive start with a bang:
  34
  35         \[[!directive ...]]
  36
  37 If you would like to keep the old syntax, it is still supported, add the
  38 following to your setup file:
  39
  40         prefix_directives => 0,
  41
  42 But it's not hard to convert your wiki to the new syntax. You can use
  43 [[ikiwiki-transition]]. It will convert preprocessor directives in all
  44 files given on the command line. To convert an entire wiki:
  45
  46         find wikidir/ -type f -name '*.mdwn' -print0 | xargs -0 ikiwiki-transition prefix_directives
  47
  48 Be sure to modify the find to list all pages in the wiki if you're using
  49 other markup than markdown. You will probably want to commit the changes
  50 when you're done too.
  51
  52 ## GlobLists
  53
  54 In 3.0, the old "GlobList" syntax for [[PageSpecs|ikiwiki/PageSpec]] is no
  55 longer supported. A GlobList contains multiple term, but does not separate
  56 them with "and" or "or":
  57
  58         sandbox !*/Discussion
  59
  60 To convert this to a modern PageSpec, simply add "and" or "or" as
  61 appropriate between terms:
  62
  63         sandbox and !*/Discussion
  64
  65 GlobLists have been deprecated for more than two years. If your wiki dates
  66 to the ikiwiki 1.0 era, you should check it for any that might have lurked
  67 unnoticed in it since back then. Ikiwiki version 2.72 will print warnings
  68 about any GlobLists it sees.
  69
  70 ## aggregateinternal
  71
  72 If your wiki uses the [[aggregate|plugins/aggregate]] plugin, it will start
  73 to aggregate feeds to special "internal" pages.
  74
  75 If you don't want this change, you can add the following to your setup
  76 file:
  77
  78         aggregateinternal => 0,
  79
  80 Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin:
  81
  82 1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated
  83    pages -- such as those in inlines. Put "internal()" around globs
  84    in those PageSpecs. For example, if the PageSpec was `foo/*`, it should
  85    be changed to `internal(foo/*)`. This has to be done because internal
  86    pages are not matched by regular globs.
  87 2. Use [[ikiwiki-transition]] to rename all existing aggregated `.html`
  88    files in the srcdir. The command to run is
  89    `ikiwiki-transition aggregateinternal your.setup`,
  90 3. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`)