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
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.
Working with content in GitHub repositories
This section goes through the workflow for adding content, editing pages, and generally working on a docs site in a GitHub repo.
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.