Review of DokuWiki

Review by Aaron Torpy

DokuWiki is a PHP-based wiki program produced by Andreas Gohr et. al.¹⁾, which is freely available for download from http://wiki.splitbrain.org/wiki:dokuwiki. Of all the wiki systems out there, I chose DokuWiki for the L3DT community wiki site because it is simple to install, easy to use, and trouble-free to administer.

In my experience, the installation procedure for DokuWiki, as outlined in the installation guide, is about as easy as it can get for such software. It was certainly a lot easier than MediaWiki, which I tried to install before DokuWiki on account of it being well known, but that ended in a complete shambles when I tried to integrate it with my phpBB forum, and thus the installation was aborted. Admittedly, MediaWiki is designed to handle huge distributed-architecture wikis like Wikipedia, so it's not too surprising that it's too complex for the mere likes of me.

Anyway, the basic DokuWiki installation procedure is to copy the script files to the desired directory on your web-server. You then need to CHMOD²⁾ the access-permissions for some of the directories so that DokuWiki can read and write files as required. If you don't have command-line access to your server, such as the case for most of the cheaper web-hosts, you can do this using an FTP client such as FileZilla (using the file properties option). This can be a little daunting for first-time newbies with little UNIX experience (such as I was), but it's really not all that tricky. You'll get the idea within a minute or two.

At this point you should have a functional installation of DokuWiki, but it's probably a good idea to mess around with some settings before 'going live'. The configuration settings are stored in the 'local.php' file in the 'conf' folder (if it doesn't exist, make a copy of the 'local.php.dist' and call it 'local.php'). One setting of particular importance is the 'authentication back-end', which is where DokuWiki stores the user-account database. By default, this is set to 'plain', meaning the info is kept locally on the server in a protected file. If you want to integrate your wiki with some other system like a forum or gallery, you have to pick one of the other back-ends that are available, but code examples are provided in the installation guide, so it's a no-brainer. In my case, where I wanted to bolt the wiki to the MySQL user-database of the forum, which is a phpBB script, I simply had to specify the 'MySQL' back-end and add some of the server settings. These steps were all explained in the phpBB integration guide, so it was hard to go wrong.

Anyway, that's about all you need do to install DokuWiki. Painless is the adjective I'd use to describe it.

By default, DokuWiki allows full read/write/delete/upload privileges to all visitors. If you're using DokuWiki for a public website, such as this, that can be a little bit generous and a little bit dangerous, as anyone can anonymously upload nasty files or delete pages. However, DokuWiki has a thing called the 'access control list' that allows you to restrict user rights on a global, per-page and per-namespace basis. As we shall see in the admim page discussion, there is a nice interface for setting ACL privileges for each page and namespace. However, to simply prevent non-members from messing with your entire wiki, all you need do is change your 'conf/acl.auth' file to say something like this:

*  @ALL     1  # read-only
*  @user    8  # read/edit/create/upload for reg. users

These settings mean that all visitors can read all of your pages, but only users (i.e. logged-in members) can read/edit/create or upload.

I only discovered the admin page recently, as it is only visible to the 'superuser' specified in the 'conf/local.php' file, and I had forgotten to add myself to the list. Anyway, if you are either the user - or a member of the group - that is specified as 'superuser', you will see an 'admin' button at the bottom-right of the page, next to 'logout'. If you click on this button, you go to the admin page, which has nice things like user-account control³⁾, and also the 'access control list' management. This latter option is worth exploring:

In the above image you see the ACL management page, which is what I've used to prevent all visitors other than myself from editing this page. Generally you would want to leave most pages with read/write/edit/upload privileges for users and read-only privileges for ALL (meaning non-members), but in some instances there may be pages you want to protect, particularly if you've got a vandalism problem like they do on Wikipedia.

Because content in a wiki is essentially unmoderated, it is important that administrators and page authors have a nice and easy way to track additions and changes. At the top of each page DokuWiki has a button that links to the index of recent changes (see example here), from which you can easily see the differences between page versions (using the blue/red glasses icon).

You can also view recent changes in the dokuwiki RSS feed, which is normally found at 'feed.php' in the wiki root directory (I've renamed mine to rss.php for reasons I can't remember). By subscribing to this news-feed in a feed-reader such as FeedReader or Opera (see RSS guide for help), you will be alerted whenever someone creates or changes a page in your wiki.

Other than some minor vandalism of Wikipedia in my youth, I had never used a wiki before I installed DokuWiki. I was very pleased, therefore, to discover that after mere minutes browsing of the syntax guide I knew all there was to know about formatting text, tables, lists and images in DokuWiki. It's very powerful, but it's also very easy.

Let's consider, for a moment, the example of a simple list:

1. Item 1
   • sub-item 1
   • sub-item 2
     • a sub-sub item
2. Item 2
3. etc…

In DokuWiki, the code to make that list (see below) is pretty much identical to the output shown above, except that '*' denotes a bullet-list item, and '-' denotes an ordered list item with numbers/letters. To nest items, you simply indent by two spaces relative to the parent. Neat, functional, obvious.

  - Item 1
    * sub-item 1
    * sub-item 2
      * a sub-sub item
  - Item 2
  - etc...

Now, let's compare with the nested-tag mess required to do the same thing in plain HTML:

<ol>
<li>Item 1
  <ul>
  <li>sub-item 1</li>
  <li>sub-item 2
    <ul>
    <li>a sub-sub item</li>
    </ul></li>
  </ul></li>
<li>Item 2</li>
<li>etc...</li>
</ol>

To do the same thing in HTML you need a much more confusing and pedantic piece of code than you do with wiki-code. By hiding all the nasty details of HTML, DokuWiki both makes formatting easier for users, and much more consistent for readers. This latter point is important when you consider that a wiki is usually a multi-author site, where inconsistent formatting from different authors would otherwise make it more difficult for visitors to 'get' the structure and navigation of each page. You can, of course, enable user-defined HTML (and even PHP!) code for your wiki to provide more customised formatting options, but for security reasons this is generally not a good idea.

Anyway, now might be a good time to refer readers to some of the complete articles in this wiki. Remember, all of these pages were written by different authors:

• Monk's ME-DEM tutorial

• JohnJ's project page

• My terragen skybox tutorial

(to do)

One of the greatest problems with all wikis is, of course, the rampant wonky spelling and grammar that is to be found in such public forums. Much of this may be attributed to legitimate typographic errors⁴⁾, rather than the declining literacy in the Western world, but in any event, a spelling-checker would really, really help.

The latest version of DokuWiki does indeed include a spell-checker. It's pretty good too.

The overall layout of DokuWiki is controlled by some PHP and CSS files in your 'lib/tpl/default' directory, the most important of which are 'main.php' (overall page layout) and 'design.css' (page contents styles). This system is very effective for adding things like custom page headers, menus and footers (such as you see on this page), which I managed to do with a bare minimum of understanding of PHP (you will need to know HTML, of course). Hacking into the actual internal layout of DokuWiki is not something I've tried yet, as I think it looks pretty neat by default, but I imagine this would require some more advanced PHP abilities.

DokuWiki does include a plugin-system, as explained on the plugins page, which adds some extra functionality. Some of my favourite plugins include:

• Note, for adding pretty notes.
• Blog, for making a DokuWiki-driven weblog.

The 'backlinks' feature doesn't always work in default build. The fix, listed here, is easy to apply.

To conclude, I found DokuWiki to be an excellent beginner-level wiki system as far as installation, administration and general use are concerned. I'd give it four and a half stars.