cf166998bb8060498222768084d2d774e038e173
[ikiwiki.git] / doc / tips / optimising_ikiwiki.mdwn
1 Ikiwiki is a wiki compiler, which means that, unlike a traditional wiki,
2 all the work needed to display your wiki is done up front. Where you can
3 see it and get annoyed at it. In some ways, this is better than a wiki
4 where a page view means running a program to generate the page on the fly.
5
6 But enough excuses. If ikiwiki is taking too long to build your wiki,
7 let's fix that. Read on for some common problems that can be avoided to
8 make ikiwiki run quick.
9
10 [[!toc]]
11
12 (And if none of that helps, file a [[bug|bugs]]. One other great thing about
13 ikiwiki being a wiki compiler is that it's easy to provide a test case when
14 it's slow, and get the problem fixed!)
15
16 ## rebuild vs refresh
17
18 Are you building your wiki by running a command like this?
19
20         ikiwiki -setup my.setup
21
22 If so, you're always telling ikiwiki to rebuild the entire site, from
23 scratch. But, ikiwiki is smart, it can incrementally update a site,
24 building only things affected by the changes you make. You just have to let
25 it do so:
26
27         ikiwiki -setup my.setup -refresh
28
29 Ikiwiki automatically uses an incremental refresh like this when handing
30 a web edit, or when run from a [[rcs]] post-commit hook. (If you've
31 configured the hook in the usual way.) Most people who have run into this
32 problem got in the habit of running `ikiwiki -setup my.setup` by hand
33 when their wiki was small, and found it got slower as they added pages.
34
35 ## use the latest version
36
37 If your version of ikiwiki is not [[!version]], try upgrading. New
38 optimisations are frequently added to ikiwiki, some of them yielding
39 *enormous* speed increases.
40
41 ## expensive inlines
42
43 Do you have an archive page for your blog that shows all posts, 
44 using an inline that looks like this?
45
46         \[[!inline pages="blog/*" show=0]]
47
48 Or maybe you have some tag pages for your blog that show all tagged posts,
49 something like this?
50
51         \[[!inline pages="blog/* and tagged(foo)" show=0]]
52
53 These are expensive, because they have to be updated whenever you modify a
54 matching page. And, if there are a lot of pages, it generates a large html
55 file, which is a lot of work. And also large RSS/Atom files, which is even
56 more work!
57
58 To optimise the inline, consider enabling quick archive mode. Then the
59 inline will only need to be updated when new pages are added; no RSS
60 or Atom feeds will be built, and the generated html file will be much
61 smaller.
62         
63         \[[!inline pages="blog/*" show=0 archive=yes quick=yes]]
64         
65         \[[!inline pages="blog/* and link(tag)" show=0 archive=yes quick=yes]]
66
67 Only downsides: This won't show titles set by the [[!ikiwiki/directive/meta]]
68 directive. And there's no RSS feed for users to use -- but if this page
69 is only for the archives or tag for your blog, users should be subscribing
70 to the blog's main page's RSS feed instead.
71
72 For the main blog page, the inline should only show the latest N posts,
73 which won't be a performance problem:
74
75         \[[!inline pages="blog/*" show=30]]
76
77 ## expensive maps
78
79 Do you have a sitemap type page, that uses a map directive like this?
80
81         \[[!map pages="*" show=title]]
82
83 This is expensive because it has to be updated whenever a page is modified.
84 The resulting html file might get big and expensive to generate as you
85 keep adding pages.
86
87 First, consider removing the "show=title". Then the map will not show page
88 titles set by the [[!ikiwiki/directive/meta]] directive -- but will also
89 only need to be generated when pages are added or removed, not for every
90 page change.
91
92 Consider limiting the map to only show the toplevel pages of your site,
93 like this:
94
95         \[[!map pages="* and !*/*" show=title]]
96
97 Or, alternatively, to drop from the map parts of the site that accumulate
98 lots of pages, like individual blog posts:
99
100         \[[!map pages="* and !blog/*" show=title]]
101
102 ## sidebar issues
103
104 If you enable the [[plugins/sidebar]] plugin, be careful of what you put in
105 your sidebar. Any change that affects what is displayed by the sidebar
106 will require an update of *every* page in the wiki, since all pages include
107 the sidebar.
108
109 Putting an expensive map or inline in the sidebar is the most common cause
110 of problems. At its worst, it can result in any change to any page in the
111 wiki requiring every page to be rebuilt.
112
113 ## avoid htmltidy
114
115 A few plugins do neat stuff, but slowly. Such plugins are tagged
116 [[plugins/type/slow]].
117
118 The worst offender is possibly [[plugins/htmltidy]]. This runs an external
119 `tidy` program on each page that is built, which is necessarily slow. So don't
120 use it unless you really need it; consider using the faster
121 [[plugins/htmlbalance]] instead.
122
123 ## be careful of large linkmaps
124
125 [[plugins/Linkmap]] generates a cool map of links between pages, but
126 it does it using the `graphviz` program. And any changes to links between
127 pages on the map require an update. So, avoid using this to map a large number
128 of pages with frequently changing links. For example, using it to map
129 all the pages on a traditional, highly WikiLinked wiki, is asking for things
130 to be slow. But using it to map a few related pages is probably fine.
131
132 This site's own [[plugins/linkmap]] rarely slows it down, because it
133 only shows the [[index]] page, and the small set of pages that link to it.
134 That is accomplished as follows:
135
136         \[[!linkmap pages="index or (backlink(index)"]]
137
138 ## overhead of the search plugin
139
140 Be aware that the [[plugins/search]] plugin has to update the search index
141 whenever any page is changed. This can slow things down somewhat.
142
143 ## profiling
144
145 If you have a repeatable change that ikiwiki takes a long time to build,
146 and none of the above help, the next thing to consider is profiling
147 ikiwiki. 
148
149 The best way to do it is:
150
151 * Install [[!cpan Devel::NYTProf]]
152 * `PERL5OPT=-d:NYTProf`
153 * `export PER5OPT`
154 * Now run ikiwiki as usual, and it will generate a `nytprof.out` file.
155 * Run `nytprofhtml` to generate html files.
156 * Those can be examined to see what parts of ikiwiki are being slow.
157
158 ## scaling to large numbers of pages
159
160 Finally, let's think about how huge number of pages can affect ikiwiki.
161
162 * Every time it's run, ikiwiki has to scan your `srcdir` to find
163   new and changed pages. This is similar in speed to running the `find`
164   command. Obviously, more files will make it take longer.
165
166 * Also, to see what pages match a [[ikiwiki/PageSpec]] like "blog/*", it has
167   to check if every page in the wiki matches. These checks are done quite
168   quickly, but still, lots more pages will make PageSpecs more expensive.
169
170 * The backlinks calculation has to consider every link on every page
171   in the wiki. (In practice, most pages only like to at most a few dozen
172   other pages, so this is not a `O(N^2)`, but closer to `O(N)`.)
173
174 * Ikiwiki also reads and writes an `index` file, which contains information
175   about each page, and so if you have a lot of pages, this file gets large,
176   and more time is spent on it. For a wiki with 2000 pages, this file
177   will run about 500 kb.
178
179 If your wiki will have 100 thousand files in it, you might start seeing
180 the above contribute to ikiwiki running slowly.