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