Using Github Pages to host a documentation site built with Hugo
Table of Contents
What is Hugo?
Hugo is an open-source static site generator written in Go. It’s pretty stable and requires a lot less maintanence than all those JS based generators. You can find the Quick Start documentation here
Build your Hugo site per the Hugo docs.
Hugo has several themes availble for documenation sites. Pick one and run with it.
Content in Hugo lives in the /content
directory. HTML and Markdown are supported out of the box.
AsciiDoc, RST, and Pandoc can be supported if you install Asciidoctor, RST, or Pandoc. More information
can be found here
Don’t forget to configure your site in config.toml
and build the static pages with hugo -D
.
Github Pages
If you want to use a custom domain for your site you will need to put your custom domain in static/CNAME
.
Github Pages deployment is handled by a Github Action. Hugo documents this pretty well. But the gist is that we want to run a job that sets up Hugo, builds and minifies the site, and then deploys it.