Easier documentation with GitHub Pages

One thing all applications need is documentation. That’s even more true of open source projects, where code is open to all and modules and libraries are reused in outer applications. An easy-to-manage web host can provide a place to put your documentation, and you can manage edits and updates with the same tools you use to write and build code.

That last requirement is surprisingly important. Documentation should be subject to the same processes as code; some organizations make it a gatekeeper for the entire release process. If there’s no documentation, then builds fail. It’s an approach that encourages developing documentation in parallel with code. Developers add documentation to Git branches, and technical writers make edits and produce pull requests.

Granting that documentation is a key component of the CI/CD (continuous integration and continuous delivery) process, we need a publication method that can be integrated into our builds. So, it’s good to see that GitHub has built a web publishing platform into its repositories.

Setting up GitHub Pages

There’s a lot to like in GitHub Pages. You can tie a set of pages to a project repository and have a set for a user or an organization. Content is stored in the repository and delivered either to a GitHub-hosted URL or to a custom domain. You can manage content exactly the same way you manage code, pushing from content development branches to main to publish new content. There’s support for defining what branches are used to publish from, as well as Actions to automate publishing.

You don’t even need to use HTML. GitHub Pages can be authored in GitHub’s own Markdown dialect, simplifying basic formatting. That makes getting started quick and easy—you can add your first page without leaving the site. All you need to do to create a personal site is add a new repository to your account, using your GitHub username, calling it username.github.io. To initialize the site, first create an index page, either as HTML or Markdown, and push it to the new repository. Go to the URL that’s the repository name to view your site.

Although the default URL works well enough, GitHub allows you to access your site with a custom domain. If you want a specific URL, a CNAME set in your DNS works well. If you prefer to make the domain name your URL, GitHub provides a list of IP addresses that need to be configured for the site. Once you’ve set up your DNS, GitHub will verify the settings before activating your domain.

You can configure your site to use TLS (Transport Layer Security) via built-in support for free Let’s Encrypt certificates. GitHub will manage certificates for you, updating automatically. The process of issuing and installing a certificate takes only a few minutes, and once it’s in place, you’re able to lock down access so only secure connections are permitted.

Using GitHub Pages with static site generators

GitHub Pages is designed to work with a new generation of static site builders, with direct support for the Ruby-based Jekyll, including a set of GitHub-hosted themes. One alternative that’s proving particularly popular is Hugo, a site building and management tool that’s written in Go and is available through many common software package distribution services. As static sites need to be rebuilt each time you make a change, finding one that’s as fast as Hugo is good, as rebuilding a site for publishing takes seconds.

There are two ways to use Hugo with GitHub Pages. The easiest option is to install a local copy and build content locally before transferring content to your GitHub repository. If you’re using Windows, you can quickly set up Hugo using the Chocolatey package manager. The Chocolatey CLI can be accessed through the Windows Terminal, where it will install and configure Hugo, set up the appropriate path, and ensure you have the latest version. Once installed, close and reopen the Windows Terminal to load an updated path and test your Hugo install.

Using Hugo with GitHub Pages

Hugo is a command line tool, which makes it ideal to use with an editor like Visual Studio Code. You can use Code to edit Hugo’s configuration files and create Markdown content, with a terminal open to run Hugo commands as needed. Code’s extensibility comes into play here too, as it can use its GitHub integration to handle uploads to your Pages repository and support Markdown to reduce the risk of errors. There are even Hugo-specific extensions to help build and manage site content.

Start by cloning your Pages repository to your development PC. Next, launch Hugo and create a new site in your clone. This creates the required site structure. You can now add a submodule to your site, installing your choice of Hugo theme and adding a reference to it in your site’s configuration file. Themes can be customized or you can use Go’s templates to create your own.

You can test the basic site functionality using the built-in server. This is a useful tool to keep running. When you save any new content, the local server will provide an updated set of pages ready for testing. The local server doesn’t compile Markdown and Hugo directives to HTML and JavaScript; it runs a local interpreter and displays content on the fly. The result is a way to preview and test pages while you build them.

Once you’re ready to publish your site, stop the local server and run Hugo to convert your site to HTML. You can then push the resulting HTML to GitHub, where it will be ready for users to see. If there are folders you don’t want to push to GitHub (for example, your Markdown content) simply add a .gitignore file to them, and your git client won’t push them to your repository.

Usefully, Hugo is extensible, using shortcodes to drop in predefined HTML and JavaScript. Many themes add their own shortcodes, especially themes designed for specific types of content or that use JavaScript to access external APIs. For example, as it’s designed to work with Markdown, there’s no direct support for HTML. By taking advantage of its Go-based templating tools, you can quickly add a custom shortcode that can wrap any HTML content you wish to include in a page.

Publishing content using GitHub Actions

Using git tools to push compiled Hugo content works well enough, but it’s not recommended for sites that need to be run by several users with multiple development branches. The Hugo development team provides a set of GitHub Actions that can help automate publishing. Users keep their own branches and use pull requests to update the main branch. When any pull request is approved, the Action runs, using a GitHub-hosted Hugo instance to compile pages and save the resulting content to a new gh-pages branch.

You can configure GitHub Pages to serve content from the Actions-powered branch so you can build an appropriate workflow for your content team. The same process works for user, organization, and project pages.

GitHub might not be your first choice as a web host, but it’s a surprisingly flexible option. It’s not able to support server-side content generation, but using JavaScript and static site generators means it’s able to deliver interactive content while supporting git-based content creation workflow. That approach allows you to integrate it with similar software development processes, ensuring that code and documentation are delivered side by side.