101 lines
5.1 KiB
Markdown
101 lines
5.1 KiB
Markdown
+++
|
|
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!();
|
|
}
|
|
}
|
|
```
|