About Viki

Overview

Viki isn't really a Wiki. It has features from both Content Management Systems (CMS) and Wikis. However, the design is deliberately intended to be biased towards a moderated site and trusted contributors, which is a divergence from the general principles of a Wiki.

Content is maintained using the Markdown markup syntax, which is an easy-to-read, easy-to-write plain text format.

The site is updated using Git to push changes via SSH to the live site. Any contributors who do not have SSH access to the site can submit Git patches via email to site moderators. Thus it is expected that such contributions are relatively small in number. If this profile of the website doesn't suit, then Viki is not appropriate and one of the many excellent open source Wikis should be used instead.

Whenever content is pushed to the live repository, a Git hook executes to update the working copy of the web-site and execute a makefile which rebuilds any Markdown documents that have changed, generating static HTML pages. To see the source of (almost) any page on the site, replace the HTML extension (.html) with (.md).

The look-and-feel of the web-site is achieved through Cascading Style Sheets (CSS). See ConfiguringRemoteRepository for more information.

Anyone can clone the site with Git to create their own (off-line) local repository. The original version of this Wiki can be cloned with:

    git clone git://www.fdsd.co.uk/viki

Implementation

We have two implementations of Viki, one primarily using GNU Make together with PHP scripting for some dynamic pages (e.g. showing search results), the other using a Ruby Rakefile together with Ruby packages to generate the HTML pages. Which version you wish to use will depend on your hosting constraints, requirments and personal preferences.

For simplicity we refer to these variants as the "Standard" and "Ruby" versions. We have set up two tracking branches for these versions which contain the bare essentials to implement your own wiki, and which you can thereafter use to track changes to the core implementation.

Standard Version

The standard version generates pages using either Pandoc or Markdown. Pandoc implements an extended version of the Markdown syntax.

Some PHP scripts have been written to provide simple index page listing and searching. However, these scripts can be removed and the site is still useful, just lacking a web based search facility.

Ruby Version

The Ruby version was created by Owen Griffin and uses a Rakefile to rebuild the Markdown documents using RDiscount to generate static HTML pages.

A HAML template is used to render every Wiki page, allowing each page to share the same layout. The Rakefile will generate a list of pages in the Wiki and place these within the template.

Requirements

Standard Version Requirements

To use the GNU Make version, the following packages are required:

Debian Packages

  • make
  • pandoc or markdown
  • libhtml-gentoc-perl (which includes hypertoc to create a table of contents when using Markdown)

For brief but full instructions for installing on Nginx, see VikiHosting.

To host with Apache, additionally install the following packages:

  • apache2
  • libapache2-mod-php5

Ruby Version Requirements

To use the Rakefile the following dependencies must be installed.

Debian Packages

  • ruby
  • rake

Gems

  • rdiscount
  • haml

Principles

The following principles apply to the design and development of Viki.

  1. Simplicity - Minimal code to support the site. Primarily leveraging the existing functionality of Git.

    It is anticipated that much can be achieved by just using Git, Markdown tools, a make file and a Git hook shell script.

  2. Security - Minimised exposure of the Web Server from attack, leveraging the security features of Git.

    With few changes to the underlying code anticipated after initial development and very little implementation code anyway, most changes are expected to be enhancements with a low likelihood of security updates being required, other than those of the underlying applications. (E.g Git, Apache, Pandoc).

    Access to the data held in the Git repository is assumed to be public and not requiring protection from being read. Where authorisation is required to read the data, this is expected to be safeguarded by the host server using mechanisms such as basic authentication.

  3. Loosely Coupled - Page content should be ignorant of its environment, although meta-data may be associated with it. This will ease the migration to any other systems in the future, whether they be upgrades of Viki or entirely new systems.

  4. Simple Markup Language - Choice of a reasonably well supported ASCII text based markup language, where the original source documents are very readable in their own right.

Related Topics: ConfiguringRemoteRepository, CreatingABlankWiki, VikiHosting

-- Frank Dean - 10 Feb 2010 -- Owen Griffin - 26 Feb 2010