Migrating to Ikiwiki

My old website consisted of static HTML files. It would have been easy to migrate that content to a new host -- just unzip the archive and let it be. The old content was ugly and non-standards-compliant, but even modern browsers display the content just fine. So why switch to a "real" CMS?

• I wanted RSS feeds for new content.
• I wanted to make the website a bit less ugly (whether I accomplished this is debatable).

At the same time, I wanted to keep things easy and simple:

• I did not want a complicated CMS like Wordpress with its endless security updates.
• I did not need (nor want) the ability to update the website via the web.
• I was (and continue to be) ambivalent about comments.
• I wanted to keep the markup straightforward, and be able to create that content in a plain old text editor.
• I wanted to be able to migrate the content away easily if necessary.
• I wanted to be able to write updates to the site at home, where I do not have Internet access.
• I did not want a strict blog. In the future I may want to organize content thematically. I did not want the CMS to get in the way of the way I organized content.
• I wanted to be able to host the content almost anywhere.

There are a paralyzing number of blog and wiki options available. So why choose Ikiwiki? A number of features stood out:

• Ikiwiki produces static HTML files. You "compile" the wiki from source files.

• The default markup language is Markdown, a simple (and fairly well-supported) language that resembles e-mail. It allows you to include standard HTML tags, which means I do not need to transition everything perfectly.

• I hate to admit it, but I effectively worship at the cult of Joey Hess, the author of Ikiwiki. In addition to admiring his work and life (he works on Free Software for a living! He has a yurt!) I look to his blog for all kinds of tech trends and best practices. Joey locks down his SSH keys and I follow suit. Joey starts moving to git, and I start fooling around with it.

  It's kind of pathetic, actually, but this hero worship has a definite upside: the cult of Joey is large, so lots of people use his software and contribute to the ecosystem. This means Ikiwiki is likely to stick around for a while. In addition Joey is a good programmer who understands security better than I do.

• Ikiwiki uses standard revision control systems for its version management. Since git is well-supported, I could use the migration as an opportunity to get used to git.

• Ikiwiki is available in Debian, which meant I did not need to install from source.

• Ikiwiki is a wiki with reasonable blogging support.

• Ikiwiki has good CSS theming support.

Overall my experience has been good enough that I am sticking with Ikiwiki for a while. Of course, there have been snags and annoyances, so I will express my gratitude for Ikiwiki by whining about its faults here.

Good Things

• It is easy to disable comments and web editing. Just comment out the cgiurl variable in ikiwiki.setup.

• Plugin support is reasonably good. The prettydate plugin made the date formatting tolerable. I was able to disable plugins I did not want (such as openid) fairly easily too.

• It took me a while to figure out how to display lists of entries using PageSpecs (the key is to use the inline directive), but once I got them working they allow you to list entries in flexible and useful ways.

• The code is pretty good. I don't know Perl well, but when I had to dig into the code to figure out what was going wrong with my RecentChanges page I could follow a reasonable fraction of what was going on.

• You can customize your own page templates (but then you have to update those templates on upgrades). I used this to put the sidebar div after the content div, because I use w3m and it aggravates me when fresh content isn't near the top of the page.

  In Debian, the default templates are in /usr/share/ikiwiki/templates . I modified change.tmpl to change the RecentChanges page and page.tmpl to change the main page output.

  The setup file makes it easy to specify alternative directories for these templates. These alternative directories can contain only your modified templates, which is important when things change.

• WikiWord syntax is not enabled by default, and it is easy to turn off. Thank heavens. WikiWord syntax is so annoying.

• The security looks pretty good, especially since I have disabled CGI. Even if I ignore this website for years (which is likely), I should not be compromising my webhost too much.

• My data remains in my control. As long as I keep my git repositories around, I have ultimate control of my data. This is really important to me.

Frustrating Things

• I want to be able to add boilerplate text to my header or footer sections, but there is no easy (and maintainable) way to do this.

• Because you are not supposed to store the ikiwiki.setup file in the same repository as your content, you effectively need two distinct repositories to keep your entire wiki in version control. I have one repository for content and one repository for configuration (including custom templates and a custom baselayout).

• Setting up a "clean" wiki (with no documentation or boilerplate pages) is not that hard, but it is not trivial. You have to override the underlaydir variable in ikiwiki.setup. Unfortunately this cannot be empty. I found I needed style.css, recentchanges.mdwn and shortcuts.mdwn in the underlay directory for things to work right.

  PmWiki gets this right, in my opinion. It maintains a strong separation between boilerplate content and your content, which makes upgrades easier.

• Ikiwiki has a setting called usedirs which is enabled by default. This puts every wiki entry into its own directory. There is a rationale for this, but I think I would prefer every entry to be its own HTML page (and perhaps use ModRewrite in .htaccess). Ikiwiki allows you to do this, but then other things (in my case the RecentChanges page) break.

• I don't like the way that Ikiwiki deals with tags. I can tag my entries arbitrarily using a tag directive. But those tags will not be clickable unless I also create a page in the tag/ directory of my wiki that has the name of the tag. That means if I want to track a new tag, I have to remember to create that entry (or I have to write a script that will make sure all my tag entries are created, which is probably what I want to do).

  I wish that Ikiwiki could automate this (perhaps using a template file). Maybe it has been fixed, and I should just upgrade.

• If you enable tags, there is a split between logical layout and physical layout. You can organize content into directories and subdirectories, but that layout is visible (and clickable -- see the "2010" link in the breadcrumb trail above). This is not ideal -- if I do not explicitly make a 2010.mdwn file (and I don't put it in the right place, which is the same directory as index.mdwn) then clicking that link gives me the underlying directory listing instead of a wiki page. This is probably another artifact of disabling CGI and web editing.

• I find that page generation is slow, and that PageSpecs in particular are expenisve. On my 400Mhz computer (be quiet. It has sentimental value), it takes several minutes to recompile my wiki even if I change a single page. I can understand that I have a slow computer, but I am surprised that generating a few pages and links takes so long. LaTeX does a lot of work to generate pages as well, but it seems significantly more efficient.

• I wish the command for regenerating the wiki was simpler. The documentation recommends placing the ikiwiki.setup file in ~/.ikiwki/, but it turns out that there is no good reason to do this -- you always have to specify the location of this file manually. Obviously a shell alias solves this problem, but I think the Ikiwiki defaults could be smarter. (My guess is that there is some security reason why this is not the case.)

• I can't relay any of these complaints/bug reports to the Ikiwiki people without doing a lot of work. I run the "stable" distribution of Debian. The version currently in Debian stable is 2.53.4. There has been a major release bump since then, and many releases within version 2. The solution to a lot of bug/request supports is "upgrade to the latest version".

  In addition, Debian stable only patches security holes. It does not fix functionality bugs. So I have three options:

  • I can live with the bugs that exist.
  • I can use an upgraded version of ikiwiki from the "testing" or "unstable" versions of Debian. There are ways to do this, but I'm not thrilled by the option.
  • I can install ikiwiki from source. This is okay but it increases the cognitive overhead of dealing with upgrades. Easy package management is one of the main reasons I use Debian!

  In short, using the stable version of Debian means I get a version of Ikiwiki that is buggy and unsupported, which is an interesting definition of "stable". This is more of a Debian complaint than an Ikiwiki one, I guess, but at the end of the day I have to decide whether I am willing to devote the energy to researching whether the bugs I have found still exist in the most recent version of the software. That rubs me the wrong way.

Other Lessons

• I can't say that I am using git extensively (or even in the proper way). When I make this website live I am just as likely to unzip the HTML files into a directory as using some fancy git method of generating the files.

• I wanted this to be the final time I had to manually migrate entries from one format to another. I did not succeed at that goal -- Ikiwiki uses proprietary syntax for internal links.

  Having said that, I found that migration was not as painful as I thought it would be. I tended to use simple markup and boilerplate code in my old entries, so some terrible Perl mangling and Vim regular expressions helped me clean up the entries pretty quickly. It was only when I got fancy that I had to put in any real migration effort.

• Ikiwiki is clever about using file creation times to determine when entries are posted. However, I really appreciated that I hard-coded entry dates in my old website. It makes me feel safer to have hardcoded dates than to depend upon filesystem properties that may or may not be preserved if I have to restore from a backup.

• In my opinion CSS is broken. If the goal is to separate content and presentation, it should not matter how I order my div entries in a source file. I should be able to position those divs on the screen however I want. But because CSS assumes that you process all data in one pass, you can't put in a main body and float in a navigation sidebar later. I understand where this design decision comes from, but I am pretty sure I don't like it.

Sidebar!

• Main
• About
• Tech
• Contact
• Archives
• RSS feed
• Recent Changes