After much gnashing of teeth we have deployed our new website… yay! This website is powered by hugo, a static site generator. This choice was made primarily because it allows us to have this website checked into git and the repository. An additional bonus is that it takes markdown as its input, which is convenient for people that spend nearly their whole day in a text editor.
We were using hugo on the old website, but not very well and it was a quite old version, the one that was obtained by homebrew. Now we’ve upgraded our hugo game substantially, and added it to the dev container so that in VSCode you can expose it with no probs.
We switched to Docsy as our theme, after two other failed attempts. Even when the code for something seems like it shouldn’t be that complex–like a website theme–it turns out that the quality, effort, and the knowlege of the people creating it is crucial. Big hats off to the google folks that created Docsy. In particular numerous other thems are so focused on adding the coolest features that they fail to do the simple things well. One theme, that shall remain nameless, was actually so complex that I could not figure out how to turn it off and had to back the changes out with git. The google folks that did Docsy have made something that is really nice.
We also switched to two new doc-generation tools:
- protoc-gen-doc for generating documentation of protobuf schemas.
- gomarkdoc for generating go documentation from source files.
Naturally, usual godoc generator is also available.