From pyblosxom to ikiwiki🔗

If you follow my blog, you know that I used pyblosxom. I switched from wordpress to serendipity, then to Pyblosxom. Now, it is time to use something else.

So this time I am going to work on ikiwiki use (and hack). I truly believe it is a really good software. First argument is that it has been written by Joey Hess, the debian-installer (d-i) developper (and many other important pieces of Debian related software). I've got a profound admiration for this guy, his stylign code and his lifestyle. A blog engine like Pyblosxom is really interesting but it lacks a space where you can work on projects. Having a tool that can't manage both seems to be better.

The next argument in favour of Ikiwiki is the fact that it is a good way to use git to manage your blog or wiki. I am not (yet !)a professionnal developper so I can't use git everyday and the time I've spend to learn to use it implies a constant use if I don't want to forget everything. So ikiwiki will be a good tool for me to always use git for things as simple as publishing an article on my blog.

Joey Hess is a Debian developper and as a consequence, ikiwiki and the majority of its plugins are very well included in the Debian archive. It's a garanty of less administration/compilation time and a good integration in the operating system of my dedicated server. Actually, this is also the operating system of my workstation ! With this configuration, you do not need any SRV binary at all with ikiwiki. You can use it on a workstation and just upload the results (static HTML files) on a passive HTTP server . Much more robustness and security because you don't have any other listening service than httpd on port 80.

It's an old school tool: you've got a real manpage, plenty of commandline tools and options. Unix

The major cons of Ikiwiki comes from the language in which it is coded: Perl ! Nearly ten years ago, I started learning Perl. With CPAN I Managed to code some really good scripts and to improve the code of Unattended. Then I discovered Python ;-) Since then, I swear Perl as much as possible. So installing Ikiwiki was a little bit scrappy for me: I had to install all those Perl packets I managed to drop over years. But to reduce this annoyment, I have to say that ikiwiki could be coded with anything else (haskell, C++, even this crappy Java): you do not have to deal with the language in which it has been coded ! As it is a real good piece of software, I found everything I needed in the installed binaries and I never had to code something !

The first task is to copy the original Pyblosxom files (articles) in an ikiwiki depot. You have to be careful about timestamps: information about the published hour and day in pyblosxom and ikiwiki is stored in the file timestamp.

So, use the -p option from cp (or scp) to copy your Pyblosxom file hierarchy and preserve timestamps.

rm every files related to specific pyblosxom plugins (for exemple a statistic plugin):

• rm -r viewcounts.dat nonces temp associations
• then ~files or #files# or .DAV directories:

for f in $(find ./ -type d); do rm -r $f/*~ $f/.DAV $f/#*#; done

I've got a hierarchy in my directories on Pyblosxom: each subdirectory under /blog is a "Category". I'd like to get ikiwiki work like this too. Actually, ikiwiki deals with what it call SubPages that are an equivalent of Categories. Indeed, you have also to use the inline directive to simulate a blog behavior: the articles from every SubPages have to be included in the blog.html page.

So here are the contents of my src_dir/blog.mdwn:

[[!inline  pages="page(blog/*/*)" show="10"]]

I use blog/\/\ in order to avoid to include SubPages that includes themselves SubPages.

Then, I have to write a src_dir/blog/Category.mdwn file for each subdirectory:

for f in $(find ./ -mindepth 1 -type d); do category=$(basename $f);
echo "\[[!inline  pages=\"(blog/$category/*)\" show=\"10\"]]" >
$category.mdwn; done

Ikiwiki use the img plugin and it's img directive to embed image files far better than the way pyblosxom done it! With Publosxom, you had to manualy make a thumbnail image and publish the two of them on the website in order to have a thing as simple as a reduced sized image that points to the full resolution one ! Time consumming. With ikiwiki, everything can be written in only one line and you have to use only a single image file.

Then you can deal with img organisation. I used to place every img file on a parralel hierarchy on the web server. With Ikiwiki, I can put the file in the same directory than the article or choose to use anything other !

I used RST to write my blog articles. It is quite a convenient language to use. No need for a web browser: you can do everything with Emacs ! There is also a rst plugin for ikiwiki but it is not recommended. But the fact is that rst format is very similar to markdown.

I thought that I'll have to use a maximum of sed rewrite rules in order to convert the reStructuredText directives to markdown format but I found another method:

aptitude install pandoc

for f in $(find ./ -mindepth 1 -type d); do for g in $f/*.rst;do sed
's/\.\. figure::/\.\. image::/g' $g | pandoc -o ${g%.rst}.mdwn
--from=RST --to=markdown; echo "[[!meta  date=\"$(stat -c %y $g)\"]]
>> ${g%.rst}.mdwn; touch -r $g ${g%.rst}.mdwn; done; done

aptitude purge pandoc

Beware: pandoc seems to not support very well the figure directive. I had to transform them to image ones (so I used a sed rule)!

This shell command line just go over your file hierarchy, convert rst files from Rst to Markdown (with pandoc) and preserve timestamps (remember the old touch command).

Just launch a refresh of your ikiwiki site, note that the conversion process is perfect and rm all those rst files !

Just a sed rule to transform a rst link: \link title http://mylink_target\\_ to a markdown link: \Link title:

sed 's/`\(.*\) <\(.*\)>`_/\[\1\](\2)/g' ./my_old_rst_file.mdwn

You don't have to use this rule if you use pandoc. I've just put it here because I take time to write it (so it could be worth of something for somebody !).

I found that my rst articles were sometimes using image hardlinks for media stored directly on the webserver (full URL with http://) which is bad: when you access the web site from https protocol, some images are retrieved with unencrypted http.

Here is a sed snippet to solve the problem:

find ./ -name "*.mdwn" -print0 | xargs -0 sed -i 's/\[\(.*\)\](http:\/\/medspx.homelinux.org/\[\1\]\(/g'

Ok, you have applied everything up and you've got your Pyblosxom articles in your ikiwiki srcdir. Here are some plugins and configuration variables to go further.

On Pyblosxom, my hierarchy was this one:

• blog/category/(index.html) --> the default page for the category (redirected)
• blog/category/article.html --> the article page

With Ikiwiki, the organisation is a little bit different (as long as you use usedir=1 in the setup file):

• blog/category/(index.html) --> as Pyblosxom
• blog/category/article/index.html --> the article page !

There is a subdirectory more ! But you cannot use ikiwiki to act as Pyblosxom because there are two different rules. The configuration that deals with this problem is called usedirs. By default, it is enabled and provides everything in index.html files instead of "name_of_the_article".html files. There is nothing to tell Ikiwiki to put a part of the blog with usedirs and another part use named html files.

but you can solve the problem by using Apache httpd redirect directives (remember: cool URIs don't change. I've been inspired by this Ikiwiki tip.

# Ikiwiki to Pyblosxom redirection
RewriteEngine On
RewriteCond $1 !^/~
RewriteCond $1 !^/doc/
RewriteCond $1 !^/ajaxterm
RewriteCond $1 !^/cgi-bin/
RewriteCond $1 !.*/index$
RewriteRule (.+).html$ $1/ [R]

Just use the favicon plugin and put a favicon.ico file with your icon on the base of the wiki hierarchy.

This was quite complicated because to use Calendar, you have to install the archive system. It is not so hard to do: put a calendar directive on one of your wiki source file and then launch ikiwiki-calendar to build an archive of every articles of the ikiwiki site.

But there was a great problem: the archive system was kind of empty. My problem could be compared to an infinite loop of archiving resulting in only 3 months of archive and a whole page with every articles ever published. I solved the problem in modifying the archive directory place (on /blog/archives instead of /archives) and changing the PageSpec in the calendar directive to avoid archiving inline pages.

I wanted to keep my old CSS/Pyblosxom style but I found that Ikiwiki default style was really clear: no need for anything else for the moment !!

If you want to change this, you can copy your unique css file from pyblosxom to a file named local.css and placed on the wiki root. Then, you can modify the template file named page.tmpl. By default, in Debian, it is located in /usr/share/ikiwiki/templates/page.tmpl. All you have to do is to copy this file in /templates/ and change your setup file.

I use to have what I call a "Navigation part" on my blog. It was used to navigate between the blog categories. With Ikiwiki, I used the sidebar plugin. It is very easy to use it to generate a (cool) navigation bar to your blog.

You juste have to write a page named sidebar.mdwn and to put something in it. For me, I just used the map directive (from the map plugin) to make a kind of dynamic sidebar: I don't have to modify anything in that file: it is always up to date with the SubPages directories.

For the style of the sidebar, you just use local.css and modify the sidebar class. Style doesn't matter with contents (well in general) !

Just use the rsync plugin. If you do not want to install ikiwiki on your server, the best thing to do is to work on a workstation and make ikiwiki export the static contents to /var/www/ or everywhere else.

I have a special page dedicated to hiking (ikihiking). The files and html pages in this directory have been generated by another software than ikiwiki. When I tried to add these files in the Git repository and make ikiwiki compile them, the index.html file was always deleted. After looking in ikiwiki documentation, it seems that for static html files that have not been rendered with ikiwiki, you have to use the [[rawhtml]] plugin.

A simple modification of the setup file and it was fixed: all of the already rendered html files (independent from ikiwiki but present in the srcdir) are simply added as they are: there is no more control from ikiwiki.

You know that reading web pages written as black text on white background can be painful (are you really sure ?). It is really the case when it comes to source code or shell scripts. It is particularly boring to read a monotone black text source, particularly when the text is very long (and the code bad written or quite complex).

One solution is to add syntax highlight to ikiwiki by activating highlight and format plugins. Then, when you want coloured source code, juste type:

[[!format  sql """
-- this is a great SQL request
SELECT * FROM YOUR_BRAIN WHERE IDEA IS IN('funny','sex','drugs','source code');
"""]]

Which results in:

-- this is a great SQL request
SELECT * FROM YOUR_BRAIN WHERE IDEA IS IN('funny','sex','drugs','source code');