Recently, I’ve spent some time evaluating ikiwiki as a possible documentation wiki for this site. It’s small size and narrow scope make it attractive over the other wiki candidates that I’ve been looking at (specifically: Tikiwiki - which is also a full fledged CMS, shop, forums, bugtracker, etc. and PhpWiki, one of the most mature wiki platforms) and it does act slightly differently from most wiki software. Because I didn’t find a single source that detailed the setting up of ikiwiki how I wanted it, I thought a getting started guide might help others too.

First of all, ikiwiki is not a normal wiki engine, it’s a wiki compiler. The wiki page contents are stared as (markdown formated) plain text files and stored in a revision control system (RCS) (e.g. git). When changes are made to the wiki contents, ikiwiki rebuilds the actual wiki as a set of html documents that are served from the web directory. This means the wiki can be updated by altering the source files or alternatively, it can be updated from the website and ikiwiki handles the page rebuilds.

This means that it is particularly easy to duplicate the contents of the wiki in a readable, usable form, using the RCS. This is particularly attractive for the dissemination of technical documentation in a structured, re-usable, re-mixable form.

Unlike a traditional wiki engine where all the scripts are in the web folder, an inkiwiki wiki is made from a number of components:

  • The ikiwiki program, which is run from the command line interface (cli or terminal). This performs all the wiki rebuilding and is called when a new revision of the source files is submitted to the repository

  • The destination directory is the folder that contains the compiled, web-browser readable files. This has all the html pages in the wiki hirarchy and (normally) the ikiwiki.cgi script wrapper.

  • ikiwiki.cgi controls the web-side wiki editing and triggers the wiki to rebuild when changes to content or settings are made.

There are also the folders that contain the wiki source. When using git, these are:

  • The source directory, which contains the working source files that are used to compile the static pages that are placed in the destination directory. No changes are made manually to this repository, only ikiwiki interacts with the contents of this directory directly.

    • A number of files (such as the user database) exist only in the .ikiwiki subfolder of this directory and are not duplicated to any other repository.

  • The repository, a bare git repository (has no working directory) that is the central repository of all changes to the wiki source. The contents are automatically updated from the source directory when web-side changes are made, and changes pushed from a working clone are automatically pulled by the source directory for rebuilding

  • Any number of working clones of the repository, where the wiki source files can be changed and updated. Changes are pushed and pulled from the repository like any normal git remote.

Something that looks like this:

ikiwiki Edit & Rebuild Flowchart

If your browser doesn’t like vector images, and won’t show the image above, click here for a “backwards compatible” version.

While this hierarchy might seem overly complex or complicated, it all runs very smoothly in practice, making changes to a working clone (usually on another computer from the web server), pushing those changes to the repository, which automatically causes the wiki to be rebuilt as required in the destination directory. If web-side revisions are made, the wiki is automatically rebuilt as they are submitted, and the changes can be pulled straight from the repository.

In the second part, I’ll go through installation and setup, along with resolving some problems I ran into from lack of knowledge.