Reviving My Blog With Soupault
Back when I was first learning to program, part of that learning experience involved rolling my own blog engine using Django. This had driven my website since it's inception, until yesterday. Join me as I discuss the how and why moving my blog to soupault!
→ In The Beginning
At the time, writing my own blog engine seemed like an obvious choice. I learn best by getting my hands dirty, and this was a great excuse to hack on some Django to improve my skills. Guided by a copy of Practical Django Projects by James Bennet, I began chiseling away at what would become my personal website and blog.
It wasn't long before I not only had a functioning application and deploy process but also the confidence to put it out there for the whole internet to see.
→ The Cost Of Ownership
Of course, with a project like that you not only own it but also any and all problems that arise with it. For a simple application like a personal blog, not much can go wrong, but things of course do go wrong.
Not only the application itself, but also the ansible-ized deploy process - as libraries and other applications updated, so too did these components. Every now and again I'd find myself doing maintenance on the project, versus building it out.
Over time, the forms I wrote for posting new blog entries would break in one way or another. When I just wanted to make a blog post, and I find out I now have to hack on the code that runs the thing, any excitement I had fizzles away quickly.
→ Losing Steam
I kept this up for several years, making somewhat regular posts and occasionally even adding new features like the radio player and integrating asciinema clips.
At some point, the blog entry submission form broke for the nth time and I decided I didn't care. I wasn't going to fix it, new posts would just have to wait. Besides, not only did I not have much to say, I figured: who wants to read it?
And so the site languished; even with inspirations for new posts coming all the time, I avoided working on the codebase because it wasn't remotely fun anymore.
By the time I started working on modding-openmw.com I had already kind of decided that I didn't like the pattern of storing things in a database (where they would become semi-special). For that particular site, things are stored in the database but seeding it all in from some python code is part of the deploy; I wanted to avoid breakage situations like what I've seen on my personal site but also reduce the possibility for data loss.
→ A New Hope
I had recently used soupault to create the MousikóFídi home page and knew that it could be used to generate a static blog, so I filed away a plan to redo my site using it. The idea of no longer needing a database or any kind of backend, but still being able to write posts and index them in a blog-like fashion, was highly intruiging. I could simplify the site and make it usable again.
→ Why Soupault
Before I get too far into it, I should address why I chose soupault over any other static site generator. Indeed, there are many popular offerings out there, though I've never really used any of them directly. So why did I want to use soupault?
One needs to look no further than the list of features at the top of the soupault home page to see the reasons why. I wasn't looking for something to abstract writing HTML away from me; I actually prefer to write my own markup and style, don't give me any "themes". Soupault is great because it allows me the flexibility to handle my own markup and style, while still giving me the power to generate things that are repeated all over.
Additionally: soupault is a single executable, and is quite fast. This entire site builds in under two seconds on my workstation, and the CI build takes around thirty seconds (usually less) to download and install soupault, build the site, and rsync it up to my server.
→ Cleaning House
I took this opportunity to clean up almost every aspect of the site's code, starting with CSS. I got rid of Font Awesome in addition to Prism that I had mentioned before, but I also had a lot of hand-written CSS that didn't really make sense when I looked at it with fresh eyes. I deleted a decent chunk of that, maybe most of it, and just decided I'd start from scratch with tweaks as I needed them.
The radio page was another area that I'd wanted to do some tidying up on for a while but just lacked the motivation. Since I was getting rid of things, the jQuery that powered the bits that fetched track info was next on the chopping block. In the previous incarnation, I used jQuery for making XHR requests that would get the currently playing track information (like title, artist, etc) and stuff it onto the page for you, the viewer. It ran on a fixed interval, 15 seconds if I recall correctly - another change I had been wanting to make was to reload the info when a track ended.
After having worked on MousikóFídi I've got a real love for vanilla javascript. Nowadays, the vast majority of browsers are good enough that jQuery isn't needed for the things it used to be. And so long story ended: I've replaced that stuff, and anything else thats javascript on the site, with vanilla javascript.
Last but not least: I've split out the part of the Django backend that talked to my MPD server to get the track information mentioned above into a tiny Flask application. It goes without saying that there's no simple way to achieve this without the backend, maybe it's possible with more javascript, but chipping this off into a single-route Flask application was the right move for me.
In the end, I could have simply copied each page into the new soupault-based project, but it really seemed appropriate to freshen a few things up. Items like the move off of jQuery are things I've wanted to do for a while, so what better time to take them on than when I'm redoing the guts of the site!
→ Importing
To get the posts off of the old, db-backed version of my site, I resorted to using raw SQL queries with psql from the command line. I loaded a recent copy of the database into a local psql server and proceeded to loop away, outputting the results into text files. I'd stick the slug, title, publish date, excerpt, and entry body into each file, which was named after the post's primary key in the database. When I was ready to load a particular entry into the site, I'd mv the file into the right place, named after the slug (with an .html extension of course).
Part of my cleaning house activities involved removing any usage of Prism.js, which I had been using for fancy code highlighting. Prism is utilized by adding CSS classes to the <code> element you want to fancy up. The problem arises when you want to take Prism away; I was left with <code> elements that had a while background (on top of the default white background the site already had). It was a really terrible look, so that's something I had to take care of on each page.
Now that the site is statically generated, I do lose some things such as blog posts by category, date, or tag views. For a personal blog, I don't see this as a great loss, and all content is still here and easily readable.
→ Soupault Goodies
Now that I'm using soupault I can benefit from some of the widgets it ships with: title, toc. Also in the mix are a few plugins and scripts: insert-if, and index.py.
This means that I can easily do things like generate page titles and tables of contents on any page, enhancing readability. The index.py script is what builds the list of blog posts you see on the index page. There are a few other widgets and plugins I look forward to trying out in the future, I've yet to try them all.
→ Delivery
The real goodie offered by soupault is the fact that the site is now a bunch of directories and files. No backend, no database, no caching. Just a webserver, serving files. I no longer have to set up a host for running Django, uWSGI, and friends; now I can just toss the generated HTML files onto my server that runs Nginx and that's all I need. A simple rsync command and that's a wrap.. it's great!
→ Into The Future
Going forward, I'd like to finally put some of the ideas I had for blog posts "to paper" as it were. Now that all I have to do is write the content, I'm left with no excuses for crickets on the site!