Dokuwiki is a wiki for small teams that’s easy to learn and a cinch to manage. I’ve explained in a previous review why Dokuwiki is a good candidate for a small wiki. In this how-to, I’ll help you get up and running with it. The information here assumes you already have Apache or similar web server running and know how to install PHP applications on it. MySQL or any SQL database is not required. Dokuwiki stores its pages as text files.
Installation #
The installation on a Debian/Ubuntu system is almost as simple as Dokuwiki’s general instructions. First, download the latest tar.gz file. (Don’t use the packages included with Ubuntu unless you have to. They’re old, and don’t contain the latest security fixes.)
cd
wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25c.tgz
cd /var/www
sudo tar xvzf ~/dokuwiki-2009-12-25c.tgz
sudo chown -R www-data:www-data dokuwiki-2009-12-25
sudo ln -s dokuwiki-2009-12-25 dokuwiki
The above commands download Dokuwiki, extract the archive’s files to your web server’s document root (/var/www), make the user account for the web server the owner, and create a shorter symbolic link (dokuwiki) to the regular directory name (dokuwiki-2009-12-25).
Now fire up your web browser and run the installer. If you installed the files to your local computer, type:
http://localhost/dokuwiki/install.php
Besides filling in all the text boxes, you may want to change the “Initial ACL policy” from the default, which makes the wiki open for anyone to edit. I changed mine to “Public Wiki”. That way, anyone can read it, but only registered users can edit it. Once your wiki is far enough along to share with others, you can change the ACL policy.
For security’s sake, you should follow the post-install warning and delete (or rename or move() the install.php file. You’ll find it at /var/www/dokuwiki.
###The Start Page
Browse to your home page and you’ll be prompted to login:
http://localhost/dokuwiki
You’re now at your home (“start”) page, but there’s a warning that the page doesn’t exist.
Click the Create this page button to load the editor. Type Welcome to my wiki. in the editing window and press the Save button.
The page has now been created and you’re already viewing it. The Create this page button has disappeared, replaced by a new button, Edit this page. Click it to open the editor again.
Learning By Example #
Click the syntax hyperlink above the text editor window (or better yet, open it in a new tab – you’ll need this as reference while learning Dokuwiki markup). Note that this help is built into the wiki, and is in fact a wiki page. The link at the top now says wiki:syntax. “wiki” is the folder and “syntax” is the page. The actual file is “syntax.txt”, and it’s stored in the wiki folder of your wiki’s document directory. Dokuwiki calls the folders you create namespaces. Namespaces work just like file directories. If you browse the document directory (/var/www/dokuwiki/data/pages), you’ll see that they are directories. You use namespaces in your wiki to hierarchically organize your pages, just as you use directories in your computer’s file system to classify your files.
Don’t just read this syntax page. Click the Edit this page button above it to see its underlying text. Notice how things like headings and lists are created. Make a change to it and click the Preview button to show how the page will look once you save it. You can learn most of the markup by studying and playing with this one page.
Adding a Second Page #
Go back to your start page. You can navigate back to it in any of several ways. You could click your browser’s Back button. However, Dokuwiki provides a quicker way: breadcrumbs. Breadcrumbs are links to your most recently visited pages. These links appear near the top, just below the action buttons, and above the page content. Click on the start link to jump to the start page. Then click the Edit this page" button once again. Add the following sentence after your welcome message, then save it.
Click here for [[how to use this wiki]].
Your page now looks like this:
The double brackets signify a link to a new page called “how to use this wiki”, shown in red. Click on the link and you’re again told that the page does not exist (that’s why the link was shown in red). Same as before, click the Create this page button, enter any text you like, and save it, e.g.
TO DO: This is where my wiki instructions will go.
Click the start page in the breadcrumbs (you can also click the name of your wiki at the very top of the page) to return to the home page. The link to the “how to use this wiki” page is now green.
Adding Sections #
Let’s add some sections to our wiki and link them to the start page. Edit the start page, skip a line below what you’re written, and add these bullet items. Be sure to indent each one by at least 2 spaces, and use an asterisk ("*") for the bullet:
* [[Jokes:]]
* [[Photos:]] of the family
* [[vital: | Important stuff]] I gotta remember
* http://youtube.com
* [[http://www.google.com | Google]]
Your start page should now look like this:
The first three bullet items are internal links – to documents within your wiki. The colon you typed following the word indicates that you are linking to a namespace, not a page. Therefore, the link Jokes: refers to the Jokes folder, not the Jokes page. You can jump to a namespace in this way just like jumping to a regular page. So what’s the practical difference between a namespace link and an ordinary page link? When you jump to a namespace, it’s like navigating to a subdirectory. Just as your web server looks for a file called index.html when you navigate to a new URL path, Dokuwiki looks for a page named start. If the start page doesn’t exist, Dokuwiki will prompt you to create it.
A vertical bar ("|") is optional, and can be used to display a different name for the link. In our example, the link is to the “vital” namespace, but the link will say “Important stuff”. You can use the vertical bar to give more meaningful names to any link – pages, namespaces, or external links. The last two links are examples of external links: they point to URL’s on the public internet, outside the wiki. Dokuwiki automatically recognizes URL’s that start with common prefixes like “http://”, such as the YouTube URL, and creates a hyperlink out of them. You often don’t have to enclose them with brackets. However, you can see that the Google link using the brackets and vertical bar is prettier.
Undoing Your Edits #
We can’t leave this initial lesson without mentioning how to correct your errors. First, like all good wikis, Dokuwiki gives you a complete revision history, allowing you to revert to earlier saved versions. In fact, Dokuwiki automatically saves your work periodically if you keep the editor open. To view past changes, click the Old revisions button. Checkmark any two revisions in the history to compare them. Dokuwiki shows you the differences using color highlighting, similar to a file “diff” utility. If you want to revert to the earlier version, click on its heading, then select the Restore button.
Also, you may be wondering how to delete a page. Dokuwiki doesn’t provide a delete button. Instead, you must first edit it, erase all the text, and then save it.
Go ahead and experiment on your new wiki. With Dokuwiki’s revision history and auto-save features, most anything you do can be quickly reversed. In Part 2 of this series, I’ll cover how to improve your wiki’s appearance and navigation.