Sometimes treating docs as code seems overly complicated. Let’s break it into component parts – static site generators, development environments, source control, continuous integration, hosting, deployment, and testing docs. Yes there is a stack here to learn, but now you can take tutorials one-at-a-time no matter where you are in a docs-as-code exploration.
Go to docslikecode.com/learn to take a look!
With this new series of online tutorials I hope to provide a simplified view of static site generators plus the continuous configuration and deployment scenarios you can use for docs like code. The idea is to show the different “adventures” you can take through docs like code tooling. Then, there are also articles that help you evaluate each of three (yes, three!) static site generators – Hugo, Jekyll, and Sphinx.
Sphinx with Read the DocsSphinx with Alabaster theme on Readthedocs.org
This combination is a powerful one, and you can go completely through from setting up a GitHub repository with Sphinx for builds and RST as source, to connecting the repo by manually setting up the webhook so that it builds automatically to readthedocs.org. The theme is the Alabaster theme, as shown. With a simple change in the Sphinx configuration you can also use Markdown as source. This possible substitution shows the flexibility of any of these adventures.
Jekyll with GitHub PagesJekyll with Minimal Mistakes theme on GitHub Pages
For this opinionated walkthrough, you learn how to set up a GitHub repository with Jekyll and Markdown as source that uses GitHub Pages to automatically deploy the web pages to a web site. The theme is the Minimal Mistakes theme, which can be easily upgraded as the theme author continues to maintain the theme. Plus, you can deploy to GitHub Pages with a single configuration setting.
Hugo with NetlifyHugo with Learn theme on Netlify
If you’re interested in a Go-based workflow with no dependencies, you could go through the Hugo scenario. Set up a GitHub repository with Hugo and Markdown as source, then use Netlify to deploy a documentation site. The theme in place is the Learn theme, based on the Grav Learn theme.
I know there are many more combinations of build systems, testing possibilities, and static site generators and I welcome more tutorials! I know Asciidoc has another great build system that has another source type. We can also learn a lot about the templating engines in each system. Please submit a pull request if you have more ideas, and please use these tutorials for workshops or self-guided learning.