Planet Open Help

The life and work of the open help community
Join our planet

September 09, 2018

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Tutorials for Static Site Generators on docslikecode.com

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 Docs

Sphinx screenshotSphinx 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 Pages

Jekyll screenshotJekyll 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 Netlify

Hugo screenshotHugo 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.

by annegentle on September 09, 2018 08:12 PM

Subscriptions

  • Anne GentleAnne Gentle Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.
  • Jim CampbellJim Campbell HRIS admin to the stars, and documentation writer for needy open-source projects. As a Chicagoan, I also know enough to not put ketchup on a hot dog.
  • Lana BrindleyLana Brindley Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.
  • Shaun McCanceShaun McCance GNOME documentation team lead. Programmer. Technical writer. XML expert. Community leader. Free software enthusiast.