Sphinx, Jekyll, and Hugo, all are static site generators that teams use for web sites and documentation sites. Let’s go through setting up a static site generator and a common CICD system with it.

If you’ve got access to a docs repository already, but don’t know what to do next, start with GitHub for documentation sites.

GitHub for documentation sites

Learning GitHub or any source control system backed by git for documentation sites takes some time and practice. This set of lessons uses the Terminal rather than the desktop application or the web site UI, though both are valid ways to do a Git workflow.

Set Up Sphinx with Python

Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version, and Python 2 is an unsupported Python version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from ReStructured text files.

Set Up Jekyll with Ruby

Jekyll is a Static Site Generator that typically accepts Markdown for authoring. Jekyll has its own documentation site and a Quickstart. To prepare your environment to build Jekyll sites locally, follow the instructions for either Windows or MacOS.

Set Up Hugo with Go

To build Hugo sites locally, install Homebrew and Hugo. You do not need to install Go to use Hugo as your static site generator. These instructions are for a Mac or Linux system, but you can also read the Windows installation instructions on the gohugo.io site.

Continuous Deployment (CD) for Documentation Sites

Continuous deployment lets you build the docs on another system and then place the files where the web server can serve them. CD can include both the building of the HTML files as well as deploying them to a host.

Set Up Automated Tests for Docs

You have choices for continuous integration systems that can run documentation tests. For this exercise, let’s make a set of minimal tests: build the docs, and check the links and image references.

Evaluating Static Site Generator themes

Themes for static site generators often provide advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables.

Evaluating table layouts and formatting

Table layout can be an annoying and difficult aspect of using simple markdown as documentation source. That said, when using Markdown or RST tables you can compare changes to simple tables more easily during reviews.

Evaluating Static Site Generator search options

Most static site generators provide a browser-side search capability, where the list of indexed keywords for search are built at the same time as the output. Learn more about considerations for each SSG in the following sections.

Templating and data-based layouts

Templates can have a couple of different definitions for content, depending on the size. You can make a template for an entire document or for a page. When talking about repositories you can also have a template for a repository.

Evaluating print, PDF, or epub output

How difficult or straightforward is it to create a print or PDF format? You may want to investigate and test solutions beyond this article, as requirements and print tolerances can vary widely.

Static Site Generator performance considerations

When you start building large documentation sites, or gluing together multiple documentation sets, you might look for performance gains in the build time. Having smaller doc sites helps with this, so that you can build with your static site generator systems in parallel, but also look for incremental builds or ways to measure build times to look for areas where the build is slowed down and then find a root cause for the slower performance.