-Is ikiwiki taking too long to build your wiki? Read on for some common
-problems that can be avoided to make ikiwiki run quick.
+Ikiwiki is a wiki compiler, which means that, unlike a traditional wiki,
+all the work needed to display your wiki is done up front. Where you can
+see it and get annoyed at it. In some ways, this is better than a wiki
+where a page view means running a program to generate the page on the fly.
+
+But enough excuses. If ikiwiki is taking too long to build your wiki,
+let's fix that. Read on for some common problems that can be avoided to
+make ikiwiki run quick.
[[!toc]]
+(And if none of that helps, file a [[bug|bugs]]. One other great thing about
+ikiwiki being a wiki compiler is that it's easy to provide a test case when
+it's slow, and get the problem fixed!)
+
## rebuild vs refresh
Are you building your wiki by running a command like this?
problem got in the habit of running `ikiwiki -setup my.setup` by hand
when their wiki was small, and found it got slower as they added pages.
-### use the latest version
+## use the latest version
-If your version of ikiwiki is not [[!verison]], try upgrading. New
+If your version of ikiwiki is not [[!version]], try upgrading. New
optimisations are frequently added to ikiwiki, some of them yielding
*enormous* speed increases.
-### expensive inlines
+## run ikiwiki in verbose mode
+
+Try changing a page, and run ikiwiki with `-v` so it will tell you
+everything it does to deal with that changed page. Take note of
+which other pages are rebuilt, and which parts of the build take a long
+time. This can help you zero in on individual pages that contain some of
+the expensive things listed below.
+
+## expensive inlines
Do you have an archive page for your blog that shows all posts,
using an inline that looks like this?
\[[!inline pages="blog/* and link(tag)" show=0 archive=yes quick=yes]]
-Only downsides: This won't show titles set by the [[!ikiwiki/directive/meta]]
+Only downsides: This won't show titles set by the [[ikiwiki/directive/meta]]
directive. And there's no RSS feed for users to use -- but if this page
is only for the archives or tag for your blog, users should be subscribing
to the blog's main page's RSS feed instead.
keep adding pages.
First, consider removing the "show=title". Then the map will not show page
-titles set by the [[!ikiwiki/directive/meta]] directive -- but will also
+titles set by the [[ikiwiki/directive/meta]] directive -- but will also
only need to be generated when pages are added or removed, not for every
page change.
to be slow. But using it to map a few related pages is probably fine.
This site's own [[plugins/linkmap]] rarely slows it down, because it
-only shows the [[index]] page, and the small set of pages that link to it.
+only shows the index page, and the small set of pages that link to it.
That is accomplished as follows:
- \[!linkmap pages="index or (backlink(index)"]]
+ \[[!linkmap pages="index or (backlink(index)"]]
## overhead of the search plugin
Be aware that the [[plugins/search]] plugin has to update the search index
whenever any page is changed. This can slow things down somewhat.
+## profiling
+
+If you have a repeatable change that ikiwiki takes a long time to build,
+and none of the above help, the next thing to consider is profiling
+ikiwiki.
+
+The best way to do it is:
+
+* Install [[!cpan Devel::NYTProf]]
+* `PERL5OPT=-d:NYTProf`
+* `export PER5OPT`
+* Now run ikiwiki as usual, and it will generate a `nytprof.out` file.
+* Run `nytprofhtml` to generate html files.
+* Those can be examined to see what parts of ikiwiki are being slow.
+
## scaling to large numbers of pages
Finally, let's think about how huge number of pages can affect ikiwiki.
quickly, but still, lots more pages will make PageSpecs more expensive.
* The backlinks calculation has to consider every link on every page
- in the wiki. (In practice, most pages only like to at most a few dozen
+ in the wiki. (In practice, most pages only link to at most a few dozen
other pages, so this is not a `O(N^2)`, but closer to `O(N)`.)
* Ikiwiki also reads and writes an `index` file, which contains information