A practical run-through of the commands used to create this ikiwiki site. On Debian Sid, using Mercurial as backend. My paths will be used as reference, exchange them wherever necessary.

Package installation

sudo aptitude install ikiwiki python-docutils librpc-xml-perl libhighlight-perl

Auto-installation script

$ ikiwiki --setup /etc/ikiwiki/auto-blog.setup
What will the blog be named? notes
What revision control system to use? mercurial
What wiki user (or openid) will be admin? daniel
warning: do not know how to set up the mercurial_wrapper hook!

Setting up notes ...
Importing /home/daniel/notes into mercurial
adding .hgignore
adding archives.mdwn
adding comments.mdwn
adding index.mdwn
adding posts.mdwn
adding posts/first_post.mdwn
adding sidebar.mdwn
adding tags.mdwn
Directory /home/daniel/notes is now set up as a mercurial repository
rcs_getmtime is not implemented for mercurial

rcs_getmtime is not implemented for mercurial

rcs_getmtime is not implemented for mercurial

rcs_getmtime is not implemented for mercurial

rcs_getmtime is not implemented for mercurial

rcs_getmtime is not implemented for mercurial

rcs_getmtime is not implemented for mercurial

Creating wiki admin daniel ...
Choose a password:
Confirm password: 

ikiwiki-update-wikilist: cannot write to /etc/ikiwiki/wikilist
** Failed to add you to the system wikilist file.
** (Probably ikiwiki-update-wikilist is not SUID root.)
** Your wiki will not be automatically updated when ikiwiki is upgraded.

Successfully set up notes:
    url:         http://d-f05.rot.sgsnet.se/~daniel/notes
    srcdir:      ~/notes
    destdir:     ~/public_html/notes
To modify settings, edit ~/notes.setup and then run:
    ikiwiki -setup ~/notes.setup

The warning: do not know how to set up the mercurial_wrapper hook! comes from a lack of support of this in /usr/share/perl5/IkiWiki/Setup/Automator.pm. I've got it working locally, and am sending a patch upstream.

The rcs_getmtime messages come from the fact that the Mercurial backend doesn't support that function (see ikiwiki/ Revision Control Systems). The implication is that ikiwiki can't restore dates of blog posts from Mercurial's history, should one have to recreate the files. It repeats 8 times since 8 files have been automatically installed as a skeleton. I've fixed rcs_getctime and rcs_getmtime for Mercurial and sent it upstream. Update: it has been accepted.

Directory structure

I prefer to keep the site in a separate directory ~/notes with subdirs (build|source).

mkdir ~/notes-tmp
mv ~/notes ~/notes-tmp/source
mv ~/public_html/notes ~/notes-tmp/build
rmdir ~/public_html
mv ~/notes.setup ~/notes-tmp
mv ~/notes-tmp ~/notes
echo "daniel /home/daniel/notes/notes.setup" | sudo tee -a /etc/ikiwiki/wikilist

The last line will make the site automatically regenerate on ikiwiki package updates.

Modifying the setup file

Below are the changes I made, described by row number and content.

 13:adminemail => 'your@email.here',
 19:srcdir => '/home/daniel/notes/source',
 21:destdir => '/home/daniel/notes/build',
 23:url => 'http://510x.se/notes',
 25:cgiurl => 'http://510x.se/notes/ikiwiki.cgi',

URL:s relative to Apache DocumentRoot are possible to declare, but ikiwiki actually parses this out by itself anyway, and currently ikiwiki --setup will spit out a number of (harmless) error messages in that exact code if the URL is already in relative format (a bug where undefined strings are assumed to be defined: currently line 570 in /usr/share/perl5/IkiWiki.pm).

 27:cgi_wrapper => '/home/daniel/notes/build/ikiwiki.cgi',

All settings so far are to reflect local conditions.

 33:add_plugins => [qw{goodstuff comments blogspam calendar sidebar more}],

more adds the !more-directive, which enables you to show only parts of posts on the main page with a "more"-link to the full content.

 35:disable_plugins => [qw{editpage}],

This is not a wiki, and I won't use the web interface to edit the pages, so I don't want it to be editable over www.

 63:timeformat => '%Y-%m-%d %H:%M:%S %Z',

Just another date format that I find as international and unambiguous as can be.

119:historyurl => '/hg/ikiwiki/notes/log/tip/<span class="createlink">file</span>',
121:diffurl => '/hg/ikiwiki/notes/?fd=<span class="createlink">r2</span>;file=<span class="createlink">file</span>',

I linked the source directory to my hgweb interface at http://510x.se/hg/ikiwiki/notes. The above lines gives a history view of the pages through hgweb.

215:comments_commit => 0,

comments_commit is disabled since the Mercurial backend doesn't support rcs_commit_staged, which is an internal ikiwiki function needed to automatically commit e.g. comments. I have submitted a patch upstream to extend the Mercurial backend to support this functionality. It works locally for me, but more testing is needed before merging upstream. See ikiwiki/ Revision Control Systems for updates on the Mercurial support. Update: it has been accepted.

336:tag_autocreate => 1,

This makes the tag list automatically update as you tag your post. I can't see why this isn't the default.

Setup calendar

Weeks start on Monday, not Sunday. At least in my world.

mkdir ~/notes/source/templates
cp /usr/share/ikiwiki/templates/calendar* ~/notes/source/templates/
sed -i 's/^\(\[\[!calendar\)/\1 week_start_day="1"/' ~/notes/source/templates/calendar* ~/notes/source/sidebar.mdwn

Otherwise ikiwiki-calendar will use the default week_start_day=0 (==Sunday) when run. Templates in the local source directory will override global ones, so by copying and modifying templates, the changes won't get overwritten during package upgrades. Newer versions of the templates, however, won't be reflected unless manually copied and re-edited. I contributed this to http://ikiwiki.info/tips/Make_calendar_start_week_on_Monday/. See that page for additions and corrections by other people.


ikiwiki-calendar ~/notes/notes.setup 'posts/* and !*/Discussion'

for initial calendar generation.

Modify crontab (crontab -e) and add

0 0 * * * ikiwiki-calendar ~/notes/notes.setup 'posts/* and !*/Discussion' 2>/dev/null

to update current date daily and generate new calendar archive pages when the year changes. 2>/dev/null since with the Mercurial backend, the command will always throw rcs_commit_staged not implemented for mercurial, which will generate an email notification. This error also means that the calendar won't actually get updated until ikiwiki --setup is run, which is an open issue. See earlier discussion about rcs_commit_staged. Personally, I don't need or use 2>/dev/null since I run my patched version of the Mercurial backend.

If you update the local templates, run

ikiwiki-calendar -f ~/notes/notes.setup 'posts/* and !*/Discussion'

to update existing archive pages (followed by ikiwiki --setup in line with above discussion concerning rcs_commit_staged).

Configure Apache

Create /etc/apache2/conf.d/notes.local:

Alias /notes /home/daniel/notes/build
<Directory /home/daniel/notes/build>
    Options +ExecCGI
    AddHandler cgi-script .cgi

Reload Apache config:

sudo service apache2 reload

Mercurial hooks

Create ~/notes/source/.hg/hgrc:

post-commit = ikiwiki --setup ../notes.setup --post-commit
incoming = ikiwiki --setup ../notes.setup --post-commit

Is this the correct way to setup the ikiwiki hooks for Mercurial? I can't find crystal clear information. A wrapper script is mentioned in places, but I don't know if it's deprecated. This seems to work without error.

Update: it should really be handled by the wrapper script generated by ikiwiki. I've sent patches regarding this in combination with the Mercurial backend upstream, and I'll update the info when it has been accepted.

Style the page

The basic theme is a good base for a personal CSS to modify appearance. Save your locally modified CSS file as ~/notes/source/local.css.

This site's local.css (if it had a name, it would probably be "pastel"). I will most likely upload it to http://ikiwiki.info/css_market/ as it matures.

Generate site

ikiwiki --setup ~/notes/notes.setup

View your creation

Go to the URL defined in the setup file and the Apache config. In my case, http://510x.se/notes.

Add to your creation

The by ikiwiki autogenerated "first post" says it all. Add pages to ~/notes/source/posts/ and commit them (or manually run ikiwiki --setup ~/notes/notes-setup or similar, see man ikiwiki. The idea of having the site in a VCS is to commit your changes, though) to make ikiwiki generate new pages (if hooks are set up). If web editing is allowed, you can also create pages that way.

By default, ikiwiki supports Markdown syntax for posts (other alternatives are available, see Supports many markup languages). Suffix the Markdown file with .mdwn to make ikiwiki pick them up.

For more info, visit primarily http://ikiwiki.info/.


I have made some patches kept (mostly) at my Mercurial repository. They will probably go upstream soon, though, when they are ready and have been discussed. They concern

  • support for rcs_commit_staged as described earlier (done),
  • support for fast retrieval of time info (done, but sketching a possibly faster method),
  • automatic merge and conflict handling when multiple edits on the same revision are done simultaneously (working, but could be more refined),
  • speed-ups regarding RCS information retrieval and parsing using XML (95% done),
  • support for rolling back pages to earlier versions through the web interface,
  • parsing of OpenID user strings (done)