Website Redesign

2021-02-18

I know a little bit about a lot of things, and one of the things that I know only in passing is web development. I am by no means qualified at or excited about web design. However, in the spirit of DIY I have always muddled through all of my own projects. This has in the past meant using a CMS of some sort, and a rather long time ago I settled on Mezzanine, a Django-based CMS written in Python.

This worked out all right in most ways. However, a few weeks back I had a server outage that I traced back to the update from Python 3.8 to Python 3.9. The virtualenv that I had set up simply stopped working, causing the web server to be unable to start as the default handler was DOA. Now, a Python virtualenv is a supposedly complete standalone environment containing the Python interpretor and libraries frozen to be version compatible with your application. It is supposed to be self contained and not dependent upon the system-wide Python installation. The fact that bumping a minor version number caused it to fail is distressing and has soured my already low opinion of Python somewhat.

Additionally, I have long desired to incorporate a full handbook into the website and do so in a way that looks seemless with the rest of the site. HitchHiker is not going to be a turnkey system for most people and will need good documentation. I have tried a few things that were available online, including Mezzanine Wiki, but nothing is really suitable and many packages are broken and/or unmaintained (including Mezzanine Wiki at the time I tried it).

Being impressed with the quality of the documentation for Rust I looked into what they use. The Rust Book is built using mdbook, which is a wonderful static markdown to html generator that does exaclt what it claims to do and does it exceptionally well. After messing with it for all of two minutes I was sold - it's just plain phenominal in use.

Having settled on mdbook for the forthcoming "Hitch Hiker's Guide to Hitch Hiker Linux" I decided that if we're going static pages there, it would be a good time to go static pages everywhere. I set about looking for a static site generator that would give me enough flexibility for my needs and still be simple to use.

While there is no shortage of SSG's available right now, there were several popular ones that I never really considered based on implementation. Jekyll, for one, is written in Ruby and I'm not looking to pollute my machine with more interpreted language cruft.

I gave Hugo a long, hard look and went so far as to install it and do some testing. Hugo is written in Go, seems to work well, and is definitely fast. However, none of the available themes were going to be suitable without a good deal of hacking.

At first glance, Zola appeared to have the same strengths and the same issues as Hugo for my use case. I really couldn't see applying any of the themes that I found directly without a lot of customization, and there were a couple that I tried that were flat out broken. On top of whatever customization I was going to have to do to whatever theme I picked, I was also going to have to adapt to an mdbook theme as well....or was there another way?

It turns out that the default set of themes that ship with mdbook are pretty much already great, and would look great adapted to an entire site. Now, mdbook itself is pretty much not suitable for generating the entire site, as I need a front page, I want to keep my blog, and I'd like to be able to incorporate other pages as well that aren't going into the table of contents for the book. But what I thought I could do is to create my own Zola template using the css from the mdbook themes.

So in the end that's what I did. Zola, written in Rust, is actually quite a bit simpler than Hugo and after a few initial trip ups getting started I'm finding the template system to be something I can navigate all right. I'm left with a two step rendering process to build the full site, as I'm rendering most of the site using Zola and the book using mdbook. But hey, I've already proven that I can do a good bit of automation using make, right?

While there's a bit more work left to finish migrating the old site, I have to say that I'm completely satisfied with my choices as of now. Both Zola and mdbook do things for me that were not going to be easily achievable in Mezzanine and come with a lot of benefits right out of the box. As a for instance, built in syntax highlighting for code snippets! Here's echo in Rust:

#![warn(clippy::all, clippy::pedantic)]
use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();
    let len = args.len();
    let n = len > 1 && args[1] == "-n";
    let i = if n { 2 } else { 1 };
    for (index, arg) in args.iter().enumerate().skip(i) {
        if index < len - 1 {
            print!("{} ", arg);
        } else {
            print!("{}", arg);
        }
    }
    if !n {
        println!();
    }
}

Tags for this post: