The "Operations" Hugo theme
Some time ago I described more carefully documenting my home data centre. In the months since I’ve found it useful to informally replicate at home some of the best-practices stuff I’ve used professionally for years.
This isn’t amazing stuff. It’s just documentation. I’m a bit of a documentation geek though.
Description of problem
(Did you see what I did there.)
I’ve had documentation before for the various computers and network devices and layouts I tinker with in my late-night leisure, but they’ve typically suffered from various, serious deficiencies:
- They’re too transient
- They’re too permanent
- They don’t record enough detail
- They don’t link
- The software to manage them may not exist tomorrow
- Okay I wrote my own software but now it’s two years later and I don’t want to use that programming language anymore
Probably the most successful solution, which I also used at work for my own notes, predated my discovery of Markdown/Commonmark and is a very similar text-based markup which I based on my experiences maintaining operations documentation for years using Twiki. But this broke down over time because it was based on a database-backed web application, so requires running a database and a web server.
One of the takeaways from this experience was that, since the markup was designed to be as simple as possible–the idea being, you could take the entire document source and e-mail it to somebody and they would find it very readable–it was really sort of too bad that the document repository had the content locked down. If the database was down or the web server was broken, the content was locked away from easy access, even just for reading.
The second most successful method I have had for documentation of my hobby stuff is writing stuff in notebooks. This keeps everything in one place and I like the physical feedback of a pen on paper. But it also becomes untidy quickly as the revision history is plain on the page, not to mention various unrelated pursuits interrupt eachother from page to page.
The third is probably text files, but as time goes by I leave little notes on this system and that system and on a couple of occasions at least I have accidentally saved important notes in directories I didn’t realize I was in.
Enter Hugo
Over the years I’ve developed documentation using various systems, and I’ve lost interest in content management systems. Every time I used one I wanted to write my own, and when I’ve done that it’s been deeply satisfying but also time-consuming and becomes an end in itself which detracts and distracts from the primary goals–what I’m trying to provide, or what I’m actually getting paid for. One documentation repository I was responsible for went through a number of iterations which eventually culminated in me getting rid of a well-respected (at the time) CMS and replacing it with a fairly simple web application where PHP handled presentation and the content was static text with minimal markup managed under Subversion. This supported multiple authors, revisions (obviously), and was way less hassle for everybody who had to touch it.
I’ve since come across Hugo and it is there for the presentation and out of my way for the creation. So when I’m writing an unnecessarily lengthy diatribe like this one, or just jotting down a quick note alongside a pasted-in code snippet, I use the tools I like for editing text, instead of some web-based editor mostly but not quite like all the other web-based editors. When I am ready to worry about the presentation, Hugo compiles all the parts together and I can tweak as necessary. These are two separate and completely distinct pleasures. (Like I mentioned above, I am a documentation geek.) I don’t like it when I’m encouraged to worry about one when I’m hard at work at the other.
I’d started to use Hugo to share some of the recent technology I’ve been exploring at work and soon I’d learned enough about it to see how I could maybe use it to make sense of my managed systems without it being a single point of failure in case of some system meltdown.
Hugo themes
A theme in Hugo, as for any other content management system, describes how content is to be presented. For straight-up documentation, the theme describes layout and prescribes style. Pretty simple, and Hugo does it well. The Operations theme uses a bare, hopefully clean and uncluttered style. It suggests the use of “Documents” and “Notes” for longer, mature descriptions and shorter, informal musings, respectively.
There are already minimal styles in the Hugo theme directory, many of them good, mature and more sophisticated than this one. But the Operations theme makes use of Hugo’s support for YAML-structured data for describing systems. Each system in my home data centre is described by a YAML document based on a common template which prescribes recording specific aspects of each system. As YAML, these descriptions could be parsed and processed for some other process in the future, and in the meantime, the Operations theme can present them in a reasonably readable format.
This is all available on my workstation running Hugo’s internal development server off the local Git repo, and on my home intranet from GitLab pages. If Hugo and/or GitLab aren’t available, I still have all the content on my workstation and I know where to find it because that discipline is enforced by having a single place of collection. Reading the Markdown or YAML isn’t a problem, so I always have the reference I need.