The last few days I’ve been helping contributing code to Frank Dean’s wiki software - Viki. Frank has been maintaining a TWiki which me and a few of his friends have been contributing our technical notes. Whenever we find something which may be of interest to others we posted it on the Wiki.

The TWiki worked quite well for a couple of years, and occasionally I contributed my notes, but then Frank discovered Git.

Instead of using a web front-end to make modifications to the content Viki uses a combination of Git and Markdown. Git manages the contributions, allowing users to submit changes by either committing to the source tree or by emailing a patch. All content is written in the Markdown syntax. Markdown is an easy to read, text based formatting language.

I’m a fan of Markdown. It allows you to write add simple styles to your text without having to include the clutter of HTML tags. The benefits aren’t immediately apparent when writing short sections of text. I find that it’s only when writing longer peices that the benefits become apparent.

Viki uses Pandoc to convert the Markdown files into HTML. Pandoc supports multiple file formats, including some extensions to Markdown to allow more complex structures such as tables. When you commit your Git working copy a post-update script is run which will invoke Viki’s Makefile. Viki’s Makefile will use Pandoc to convert all the files to HTML including a custom header and footer. You can invoke the conversion manually by running make from the command line.

It is very simple to create your own wiki using Viki. Here are some simple instructions for installation on Ubuntu. Firstly you need to clone the Git repository:

cd ~/workspace/
git clone git://www.smartpixie.com/viki

You then need to ensure you have the Pandoc and make tools installed.

sudo apt-get install pandoc make

If you want to host your wiki locally then you need to install a web server such as apache and copy the configuration files across:

sudo apt-get install apache2
sudo cp etc/apache/viki /etc/apache2/conf.d/
sudo cp -Rv ../viki /var/www/

By using both Git and Pandoc Viki is able to replicate the basic functionality of a Wiki using very few lines of code. By leveraging the power of Git you gain a colaborative website and by using Markdown pages can be written very simply.

Because Viki generates its pages and has no dynamic server-side components it is also inherently secure. (hopefully)