I am optimistic that one of the popular static site generators can help me reach my goals for an improved Sawppy documentation site. But the site generator itself is not enough, there are a few other details I’ll have to investigate. The primary one being ability to preview changes to pages earlier rather than later in the pipeline.
Today’s flow of editing markdown files can deliver immediate feedback because GitHub has a “Preview” tab on its built in Markdown editor. But once we’re no longer directly using GitHub’s simple Markdown transformation, we’ll lose that ability. Contributors should not be expected to set up a SSG environment on their computer in order to see the results of their work, and asking maintainers to review every change on their own SSG environment would not scale. (I say this using plural as if Sawppy has a big maintenance staff… it’s actually just me.)
The answer is to bring in tools from the continuous integration world, where tools exist to preview changes to a website before deploying live. Some use services like Netlify, which is not itself open source but there is a free tier available.
One example: look at the repository for Write the Docs website. Open one of the pending pull requests and click on “Show all checks”. One of them is “Read the Docs build succeeded!” and clicking “Details” will bring up a version of the site built with changes in the pull request. This is an interesting venue of investigation to learn more about.
This was the point where I ran out of steam, and the Write the Docs meeting ran out of time, but I have a big treasure trove of pointers to investigate and keep me busy for a while.
Other miscellaneous notes:
- Project Tetra is a hardware project that has a documentation publishing system that uses Docsy and Hugo. It also uses PlantUML and Graphvis to render diagrams.
- Markdown is not the only lightweight markup language, here’s a list on Wikipedia.
- It is quite clear Hugo is not the only documentation system out there, Wikipedia has many more in a list.