hhl/content/news/website-redesign.md

+++
title = "Website Redesign"
date = 2021-02-18
[taxonomies]
tags = ["Site News","Web Programming","css","html","Zola","mdbook"]
categories = ["Site News"]
+++
I know a little bit about a lot of things, and one of the things that I know
only in passing is web development.<!-- more --> 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](https://github.com/rust-lang/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](https://gohugo.io/) 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](https://www.getzola.org/) 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:
```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!();
    }
}
```