Greg Hewgill (ghewgill) wrote,
Greg Hewgill

on collaborative text editing with ikiwiki

I think I finally found a wiki engine I like: ikiwiki. It just seems to do everything right:

  • The wiki pages and history are stored in a proper revision control system (I'm using Git, but ikiwiki supports Subversion and some others too). This is better than the wiki author reinventing a poorly specified, noninteroperable, nondistributed, fragile RCS without tagging, branching, merging, etc.
  • As a consequence of the above, I can edit my wiki text in a proper text editor without having to use the anemic <textarea> editor box in my browser. I just edit the files using vim in a git clone, committing as I go, and then push the changes up to the master repository. Of course, ikiwiki still supports the traditional <textarea> browser box if you want.
  • As a further consequence of the above, I can edit my wiki without having to have a live connection to the net. I just make changes offline and push them back up when I've got a connection. No more inconvenient page locking or edit collisions caused by a substandard revision control system. I have a simple non-RCS-backed install of ikiwiki on my laptop to preview changes.
  • ikiwiki does not need to implement its own page history browsing. It just links to your RCS web interface (gitweb, in my case).
  • ikiwiki compiles all your normal wiki pages to static HTML files. There's no extra load on your web server when people are just browsing pages. Only when somebody edits a page does it kick off a server script to handle the edit. (Changes made elsewhere and pushed up to the repository are handled by a post-commit hook that regenerates modified pages.)
  • As a consequence of the above, it is trivial to take a snapshot of an entire wiki - just copy the HTML files. Other wiki engines need some kind of "export" function, which they might not even have (I'm looking at you, DokuWiki).
  • ikiwiki uses the Markdown markup language, which is more flexible and more readable (as source) than most wiki markup languages. It's flexible because you can embed any HTML whenever you like, if you need to do something not otherwise supported by Markdown.
  • ikiwiki has a plugin architecture, and many of the standard features (such as the use of Markdown, or the username/password authentication) are in fact plugins to the base engine.
  • ikiwiki is a cool name, and it even contains a "kiwi"!

I set up ikiwiki on my server as follows:

  • I made a user named wiki which holds ikiwiki's version of the source pages (used for page generation, and also used for committing to the master repository). This also holds control information like the user database if you're using that.
  • The destination HTML directory is in my web server tree set up with the correct permissions so the wiki user can write to it.
  • The git bare repository is in a common location (/pub/git/wiki.git) with group permissions so both wiki and my own user account can write to it.
  • I set up gitweb so it can see /pub/git/wiki.git, and configured ikiwiki's history links to point there.
  • I set up ikiwiki's edit CGI (which runs suid as the wiki user) and its post-commit hook in /pub/git/wiki.git.
  • From my own user account, I can git-clone the repository and work away. Locally, I can run a stock ikiwiki at any time to preview the results as I edit.

The whole arrangement works so smoothly it's a wonder that people still use old-style wikis. Highly recommended.

  • Post a new comment


    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded