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 – Sphinx, Jekyll, and Hugo.
If you’re not sure whether to go ahead and pay for that GitHub account for access to private repositories, check out this article, GitHub Pro Account or GitHub Free Account for Technical Writing?
Sphinx with Read the Docs
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. Don’t miss the additional post on this site, Tips for Publishing Python Sphinx with Free Hosting on GitHub Pages.
Jekyll with 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 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.