I am (thinking of, I must admit) using Hugo for writing documentation.
(The alternative I’m considering is Sphinx, but we already have a fairly sizable GitLab wiki written in Markdown so I’m considering Hugo because of that. We also have other Hugo static sites so it would be a better fit rather than introducing a new tool…)
What we’re doing right now is documenting services in the sysadmin team. I’ve built this “template” (as in “a file to copy-paste in when you create a new one”, like Hugo’s Archetypes, not as in “a Hugo template”) that we start from when doing new docs. This works well, for new documentation: it forces us to think about all the little bits and pieces we often forget to document (what to do in case of fire?!) or even sometimes implement (backups!!!), so that’s good.
But. What happens when the archetype changes? It’s actually constantly evolving: as we document more and more parts of the infrastructure, we think of new gray areas we forgot to document elsewhere, so we add parts to the archetype. But then services that are already documented don’t have those pieces!
I know I could start messing around with “shortcodes”, but this seems like a poor fit: this is a template for an entire document, a “fill in the blanks” thing. A shortcode would be too unwieldy…
This might not be something that Hugo can solve by itself. What I’m thinking of would be some sort of third-party tool that would parse my Markdown template, evaluate the “parse tree” (if there’s such a thing in markdown) and do the same with the service page, and evaluate compliance, suggest improvements and so on.
Does that make sense? do people know of such a thing?
I could start working with Markdown parsers and see if I can hook in there in the right place, but I thought I would ask here beforehand, to avoid wasting any brain cycles.
Update: I think what I want is basically something like cookiecutter, but that can be used on existing files and that is not a huge templating system. There’s a thing called scaraplate which kind of does this, but it doesn’t know how to “merge” markdown files, which is fundamentally the problem here I guess. I also found another tool called
mdsaw which merges and splits markdown files, but it doesn’t deduplicate headings and doesn’t use a markdown parser (just regexes).
Update 2: turns out that Hugo has Archetypes that are pretty close to the templating system I use now, but it doesn’t support updating existing content. I updated the text here to replace “template” with “archetype” as appropriate, thanks @pointyfar for the pointer (no pun intended).