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.
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.