Build Your Own Wiki Software With Ikiwiki

Installing and Configuring Ikiwiki

Use your favorite package manager to install the “ikiwiki” package. If you don’t have a favorite package manager, try Synaptic in the System -> Administration menu. Don’t quit your package manager just yet — you still need to install a revision control system. On Jaunty (but not other versions of Ubuntu) you also need to fix bug #375159 before continuing by running the following command:

sudo sed -i '28 s^/usr/local^/usr^' /usr/share/perl5/IkiWiki.pm

Ikiwiki tracks changes using a revision control system. This article pairs Ikiwiki with the Git revision control system, but you can use other systems instead. Use your favorite package manager to install the “git-core” package. If you plan to let users view page history using the Web server on this computer, also install the “gitweb” package. After installing Git, open a terminal emulator and run the following command:

ikiwiki --setup /etc/ikiwiki/auto.setup

Ikiwiki asks you to name your wiki, name your account, and enter a password for your account. It also asks for the name of the revision control system you want to use — answer “git”. As Ikiwiki sets up your wiki, it prints the information you’ll need later. I suggest you save this list of information.

In the list, locate the three settings labeled “repository”, “srcdir”, and “destdir”. These point to your wiki’s git repository, source directory, and destination directory. The repository stores your wiki’s revision history. If you want Git Web to display this history for everyone to see, run the following two commands to move the repository and tell the source directory about its new location.

sudo mv wiki.git /var/cache/git/
cd wiki
git config remote.origin.url /var/cache/git/wiki.git

The destination directory stores your wiki’s HTML files. Ikiwiki creates it in the public_html subdirectory of your home directory, which some Web servers automatically host; see the list Ikiwiki printed for the location of your wiki on the Web. You can leave your destination directory alone while you try Ikiwiki. Later, you may want to manage pages outside of your public_html directory. If so, move your destination directory to wherever you keep your website files; for example: /var/www or /srv/www.

If you move any of these three directories, you need to update your Ikiwiki setup file. Ikiwiki listed the name of this file earlier with the rest of your settings; its name ends in .setup. Open the file and update the following settings: srcdir, destdir, and git_wrapper. You may also need to change the url, cgiurl, and cgi_wrapper settings to reflect the new location of Ikiwiki on your website. Whenever you change an Ikiwiki setting, re-run the Ikiwiki setup command. For example:

ikiwiki --setup wiki.setup

Editing Your Wiki

Unlike other wikis, you can create, edit, or delete Ikiwiki pages from anywhere. You don’t even need a Web server. Activating this feature requires only a little extra setup. Start by making a copy (clone) of your repository with the following command.

git clone wiki.git mywiki

Git creates the directory mywiki and fills it with all the files in your wiki. You can begin editing files in this directory immeditely. You don’t have any files yet, so I suggest you start by putting something in the file mywiki/index.mdwn. Later, Ikiwiki will turn this file into the index.html file that everyone sees when they first visit your wiki. You can open index.mdwn in any text editor — vi, Emacs, Gedit, Kate, or even OpenOffice.org — but you must save it as text with a .mdwn file extension. For help formatting this file, see the formatting section below. Now go to your terminal emulator, change directory (cd) into the mywiki directory, and run the following three commands:

git add index.mdwn
git commit index.mdwn
git push

The first command adds index.mdwn to Git’s revision log. The second command asks you to describe the changes you made; you can write, “created new index file.” The third command sends both index.mdwn and the log to the git repository. The git repository saves index.mdwn and the incoming updated revision log. Then it runs a script Ikiwiki installed, the post-commit hook, which copies index.mdwn, converts the copy from Markdown into HTML, and places the HTML in the destination directory. If anything goes wrong, Git prints an error on your screen. Repeat steps two and three every time you edit a file; repeat all three steps everytime you add a new file.

View your new wiki page by browsing to the location of Ikiwiki on your Web server or to the destination directory. For example, substitute your username and wiki name for <username> and <wikiname> below: http://example.com/~<username>/<wiki_name>/ or file:///home/<username>/public_html/<wiki_name>/index.html.

You can use the git clone command as many times as you want to create additional copies of your wiki. Git has special options to the clone command that let you create remote offline repositories. If you’re interested, read the manual page with the following command: man git-clone. If you make more than one copy, or if you let people edit pages over the Web, you should run the following command twice in the mywiki directory — once before you start editing a page and once before you commit it: git pull

Formatting Wiki Pages

Many wikis use their own frustratingly peculiar syntax. For each different wiki, it seems, you must learn a whole new markup language. Ikiwiki partially solves this problem by letting you choose the markup language you want to use. Ikiwiki uses the Markdown format by default, but you can also use ReStructured Text (RST), plain HTML, and a Wikipedia-like syntax. New markup languages come as plugins, so you can add more by enabling plugins. See the section below for details. Ikiwiki looks at file extensions to figure out which markup language each article uses. For example, the extensions .mdwn, .rst, and .html mean, respectively, the formats Markdown, ReStructred Text, and HTML.

An empty line creates a break.

A break between two paragraphs.

> A greater than symbol creates a blockquote.

Four spaces create a <pre> block wrapped in <code>
`inline code` can be wrapped in backtics
*italics (html emphasis)* _also italics_
**bold (HTML strong)** __also bold__
[Example.com](http://example.com).

[[!tag  article linux ubuntu]]
[[!pagecount ]]
[[!inline  pages="blog/* and !*/Discussion" show="3"]]
[[!img  2008/chlug-group.jpg caption="Original 2008 Group Photo"]]

Plugins

Ikiwiki includes two sets of plugins and a numerous ungrouped plugins. The first set of plugins enable by default the features most people expect from even the most basic of wikis. For example, Markdown fomatting and a CGI script that lets users edit pages on the Web. Ikiwiki’s author named the second set of plugins “goodstuf” and describes them as, “not too intrusive, work well with little configuration, and nice to have on any capable wiki”. Ikiwiki disables these plugins by default, but a single change to your Ikiwiki setup file enables them. Ikiwiki also includes dozens of other plugins. Take a look at Ikiwiki’s Plugin page for the complete list of over 100 included and third-party plugins.

Enable plugins that came with Ikiwiki by adding their names to the add_plugins variable in Ikiwiki’s setup file. Disable plugins that Ikiwiki enabled by adding their names to the disable_plugins variable. For example, enable the search plugin and the whole goodstuff plugin package but disable password logins:

# To add plugins, list them here.
add_plugins => [qw{search goodstuff}],

# To disable plugins, list them here.
disable_plugins => [qw{passwordauth}],

Now use the links on the Ikiwiki plugin page to download thrid-party plugins you want. Place the files in the ~/.ikiwiki/ directory and add their names to the add_plugins variable as described above. Get the name of a plugin for the add_plugins variable by subtracting the .pm file extension from its filename.

Some plugins require configuration and some plugins support extra options. In both cases, you will set variables in the Ikiwiki setup file. For details about configuring specific plugins, read the plugin’s page on Ikiwiki’s website — every plugin has a page. Ikiwiki’s setup file describes most of the variables of plugins that come with Ikiwiki.

Changing The Appearance Of Your Wiki

Ikiwiki’s has a very plain default theme — you might even call it barren. Ikiwiki’s author may prefer it this way, but he also made the layout easy to modify. Almost all of Ikiwiki’s HTML elements have an ID or class, so you can layout your wiki using CSS. Instead of modifying the main Ikiwiki CSS file, Ikiwiki suggests you put your layout into the local.css file. Create this file in the mywiki directory, add some CSS, save the file, and run the following three commands. Ikiwiki automatically points to this file on every page of the wiki.

git add local.css
git commit local.css
git push

You can only do so much with CSS; you can’t, for example, use CSS to add a new element to a page. You can, however, edit Ikiwiki’s template files in the /usr/share/ikiwiki/templates directory. Ikiwiki combines these templates with your wiki pages and renders the result using the HTML Template Perl Programing Language module. Although you can edit the templates directly, I suggest you copy the directory using cp -a and make the templatedir variable point to your copy. If you need help editing the templates, start by reading the module’s comprehensive manual page with the following command: man 'HTML::Template'

Conclusion

In this article, we’ve only set up the bare bones of an Ikiwiki. It works and there’s nothing else that you need to do, but with over 100 plugins, I couldn’t describe everything Ikiwiki can do without writing a book, so I leave it to you to explore this uniquely flexible wiki. I suggest you start with the Ikiwiki home page: not only does it run Ikiwiki, but on it you can see many of the optional plugins at work. You’ll also find comments and suggestions from people that use Ikiwiki in all sorts of innovative ways.