Home Articles

Making a static site easy

I used to think I wanted a crazy cool website to hold all my musings. I was wrong. Its more hassle than its worth and most of the frameworks to make it yourself are riddled with security holes and new ones are found all the time.

So I've opted for a simple static site hosted on an OpenBSD VPS and served up by OpenBSD's own httpd. Really can't get more secure than that.

The workflow around updating and adding new content to the site was, and is, the funnest piece around maintaining the site in my opinion, and I use a few cool tools which I'll elaborate below.

To start with, I use Vim to write everything. Once you know how to use Vim properly, nothing beats it for editing text. Add in the various plugins to extend it and make it work how you want, and you become a god amongst text characters printed on a terminal.

However, no poor soul should have to write HTML manually. Even with the power of Vim, that becomes a quickly tedious task that would make anyone give up attempting to manage their own site. So I use two tools together to make it a breeze.

First off I use the Vim plugin VimWiki. This plugin is really powerful in of itself. You can use it to manage an entire local wiki all within Vim written in Markdown and is what I also usually use to document new tools and processes as I set them up at work and at home. Additionally, it has the power to convert all the markdown you write directly into HTML, however its generation leaves a lot to be desired, and if I were using it in a vacuum for the site, I think I'd still run into some of that manual HTML writing I mention above.

So in conjunction with it, I use a fantastic tool provided by Roman Zolotarev, Static Site Generator 2. This will take any markdown you've written and generate it into clean HTML, additionally placing in a header, footer and any CSS you may want. I've found this to be the cleanest setup for both writing and generating a site in as minimal a workflow as possible, all from the CLI!

If you want to go along with this workflow at well, one workaround I needed was the ability to make sure my links generated by VimWiki were properly formated for the HTML generated by SSG2. This meant simply appending a .html to the links before saving the files where the links appears.

For this a simple substitution keybind in your .vimrc is all that is required:

nnoremap <leader>ht <Esc>:%s/\.html)/).html/g <CR>
nnoremap <leader>th <Esc>:%s/).html/.html)/g <CR>

This will simply move the .html in and out of your link spaces so you can still use VimWiki to jump between the Wiki Spaces and then have them properly formatted for generation.

As for pushing the content up to my site, I could use scp or rsync, however I'd rather not have to issue another command. What I use instead is my typical backup solution, Syncthing. It's a really cool, meshnet style syncing service. With this, I have a mesh of folders between my home server, my home desktop systems, my VPS, my phones and my work laptop. It runs on basically anything, and is super lightweight.

With this, I simply save my VimWiki's into a folder syncing to my VPS. Once everything is sync'd after save, on my vps I simply run

doas ssg2 jessi/site /var/www/htdocs/hubcaps.tech 'Hubs Lab' 'https://hubcaps.tech'

And there you have it, a full static site all from the CLI.

2018 Jessie Moss - Hubcaps