Birth of a Website

Created Thursday 18 July 2024

Kept you waiting, huh?


So, today is the day I finally dedicate my humble little VPS to it's intended role.


This project won't cover the actual setup of the server, which is the latest and greatest OpenBSD. Nor with it cover the setup and configuration of acme-client(1) and httpd(8) to serve up this very page, although those particular setups may be coming down the pipe later on! Rather, this will cover the process of generating the static HTML documents that comprise this website.


This page will be split into two discrete sections:


Write-up


Analysis Paralysis

The last time I touched webpage creation was almost two decades ago. And even then, the Seamonkey designer left a lot to be desired. Diving into my options today, I was immediately swamped with a smörgåsbord of choices: full-blown CMS suites, beefy static site generators, the whole works!
In order to curb any errant rabbit-holing on my part, I set a simple list of requirements for my particular site:

The most optimal solution I found was to make use of AsciiDoc in combination with AsciiDoctor. This would allow me to quickly and easily automate pushing updates to my web server, and AsciiDoc's superior syntax as compared to Markdown would allow a great deal of flexibility and customization.
However, learning AsciiDoc and creating all of the infrastructure around it would have added a considerable amount of time to this process. To be clear, this will be the method I employ in the future once I have a better grasp on both AsciiDoc and Web design as a whole. But as I am very much a complete newbie at all of this, that will have to wait.
Right now, I want an easy way to author pages and publish them.
So I went with the most practical option: making use of what I already have. In this instance, that would be the excellent Zim desktop wiki.


Invader Zim

I've used Zim for the better part of over half a decade now to take all of my notes and write all of my personal guides, and it's built-in web server has come in handy on more than one occasion where I needed to copy-paste commands between systems!
Zim also includes the ability to export it's notebooks to a variety of formats: the most pertinent one in this case was as a static collection of HTML pages. This is perfect for my use-case: I can author pages, preview them with the integrated web server, and once I am satisfied, run an export operation and upload the results to my server.
We have a winner!
However, an issue presented itself fairly quickly: the integrated Zim templates, to put it mildly, look terrible. Zim, fortunately enough, provides the ability to insert your own HTML templates, and I will likely pursue creating my own as part of my initial journey into Web development. For the time being, however, I perused Zim's admittedly short list of available templates, and decided on Eight-Five-Zero by John R Marks, IV.
Now the site looks, at the very least, serviceable!


Fugu

With all the editing and previewing now concluded, it's time to actually export and upload the pages!
Zim has two options for exporting pages: within the GUI under File > Export, or on the command-line using zim --export. I began with the GUI approach as a proof of concept, and quickly switched to the CLI method as part of a shell script to automate the process.
OpenBSD has the ability to serve gzip-compressed pages, provided you precompress them. A simple find(1) one-liner can accomplish this for us.
File transfer is easily accomplished using scp(1); rsync(1) is also a valid option, but was not necessary for the moment. From there, the files were moved into the document root of the Web server, and were available for display immediately.


Executive

Once the pages have been written in Zim, it is a simple matter to export, process, and upload them.
The export directory is cleaned in advance, as Zim's overwrite option does not do this cleanup for us. 

find [export dir] -mindepth 1 -delete
zim --export --output [export dir] --format html --template EightFiveZero [source dir]
find [export dir] -type f -exec gzip -9k "{}" \;
scp -r [export dir] [remote server]

Finale

That was all there was to it! Not too bad for baby's first time.
Currently, things are still very barebones: the page is plain old HTML 4, and there's not much in the way of favicons or other niceties yet. I hope to resolve this with template edits, and in much greater depth with my planned move to AsciiDoctor-generated pages.


Backlinks: Technical Projects