dmo.ca/ blog/ Converting vimblog to ikiwiki

Until today, this blog ran on vimblog, a hand-rolled minimal script for displaying blog entries. In the last year or so, though, I've become a convert to git, and so what I really want to do is edit my posts on any system, commit them to a git repository, push to a remote and have them end up as blog entries on my server. Fixing vimblog to do this would have been more work than I want to deal with, but thankfully ikiwiki exists, and can do most of what I need.

So, as of now, this blog is in ikiwiki. To get there, I followed (more or less, since I'm documenting after-the-fact) these steps:

  1. . Get ikiwiki. I use debian so this was easy.

    $ apt-get install ikiwiki 
    

    It's not the newest version, but it's adequate for my needs.

  2. . Create your working copy. Unlike the default ikiwiki instructions, this assumes that your blog will live under 'blog' in whatever your document root is, and that you will be placing your ikiwiki.setup file under version control instead of in $HOME.

    $ mkdir -p ~/ikiwiki/wiki/blog
    
  3. . Create your bare git repository.

    $ ikiwiki-makerepo git ~/ikiwiki /home/git/ikiwiki.git
    
  4. . Copy the default ikiwiki.setup file to your ikiwiki directory:

    $ cp /usr/share/doc/ikiwiki/html/ikiwiki.setup ~/ikiwiki
    
  5. . Edit ikiwiki.setup and make your necessary changes.

    $ vi ~/ikiwiki/ikiwiki.setup
    

    The main entries you will want to change are:

    • wikiname, a title for your main page
    • adminemail, your email address
    • srcdir, where the working copy lives. For this example, /home/dmo/ikiwiki (you cannot use shell variables or the ~ in this file)
    • destdir, where the publically viewable HTML should go. For this example, /var/www/dmo.ca
    • url, the URL used to reach the files generated into destdir. Here, http://www.dmo.ca/
    • rcs, here, git. If you want to use SVN, darcs, etc, find yourself another tutorial.
    • under wrappers, uncomment the { } block for git. In it, change wrapper to be the full path to the hooks/post-update file in your bare repository. This is where the post-update hook that regenerates your HTML will go. For this example, it's /home/git/ikiwiki.git/hooks/post-update
    • rss, 1 if you want rss feeds, 0 if you don't.
    • atom, 1 if you want atom feeds, 0 if you don't.
    • add_plugins should probably contain at least: goodstuff more wikitext camelcase map tag sidebar pagestats but you may want others.
  6. . Convert your old vimblog posts. You will need the vimblog-convert script. Save it, make it executable, and run:

    $ vimblog-convert ~/.blog/entries ~/ikiwiki/wiki
    

    It requires Perl 5.10 for given() / when() blocks, but if you need to run it on something older, it's not hard to remove that dependency.

  7. . Change into your working directory and add your newly-generated files:

    $ cd ~/ikiwiki
    $ (echo .ikiwiki; echo '*~') > .gitignore
    $ git add .gitignore
    $ git commit -m "Add .gitignore"
    

    $ cd wiki $ git add blog.mdwn blog/.mdwn tag/.mdwn $ git commit -a -m 'Conversion from vimblog via vimblog-convert`

  8. . Run ikiwiki's setup tool to create the git post-commit hook and generate your HTML output:

    $ ikiwiki --setup ./ikiwiki.setup
    
  9. . Push your new ikiwiki blog up to your bare repository

    $ git push
    

    This should update everything again.

Once all this is done, you can start tweaking ikiwiki plugins, changing your CSS, adding templates, etc.