Creating a Company Handbook

I recently (e.g. today) discovered Hugo Modules. I have also been investigating the possibility of using a static site generator to create a company handbook, something along the lines of the one Gitlab has.

The discovery of Hugo Modules means that I should be able to maintain a core site with the various teams maintaining their own sites to be included during the build.

For example we could start with a section on Company Values and then have sections for each of the teams which they would be responsible for maintaining in separate repositories.

Getting Started

First make sure you’re using the latest version of Hugo and Go. Modules support arrived in Hugo with version 0.56, but it never hurts to ensure you’re on the latest version:

$ brew upgrade hugo
$ hugo version
Hugo Static Site Generator v0.69.0/extended darwin/amd64 BuildDate: unknown
$ go version
go version go1.14 darwin/amd64

Then we can create our new site and initalise it to use modules:

$ hugo new site hugo-handbook
$ cd hugo-handbook
$ hugo mod init github.com/darrenparkinson/hugo-handbook

Adding a Theme

At this point you’d normally add a theme for your hugo site by either copying one into your site or by using a git submodule add command (which I’ve always disliked). Now though, we can simply add the url of the theme to our config file and hugo modules will retrieve it for us when we run hugo serve.

For the purposes of this, we will use one of the themes from the documentation section of the hugo themes site, in this case the Book theme. The theme you choose will ultimately determine how you mount your other repositories, but it will likely be quite similar.

With a config.toml like this:

1
2
3
4
5
6
7

baseURL = "http://example.org/"
languageCode = "en-us"
title = "Company Handbook"

[module]
 [[module.imports]]
   path = "github.com/alex-shpak/hugo-book"

We can now serve that and hugo will go and download the relevant module:

hugo serve -D
hugo: downloading modules …
go: downloading github.com/alex-shpak/hugo-book
...

So much better!!

At the moment, browsing to http://localhost:1313 is going to be quite boring, so lets add some content.

Adding Content

By default, importing a module appears to assume that it’s for a theme. For content, you can basically mount any repository containing content, it doesn’t have to be anything special, but when you mount it, you just have to specify a target under content/ for it to put it in the right place:

Our config.toml now looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

baseURL = "http://example.org/"
languageCode = "en-us"
title = "Company Handbook"

[module]
 [[module.imports]]
   path = "github.com/alex-shpak/hugo-book"

[[module.imports]]
    path = "github.com/darrenparkinson/hugo-handbook-values"
    disabled = false

    [[module.imports.mounts]]
    source = "."
    target = "content/docs/values"

You’ll notice that the target is content/docs but that is specific to this theme. The theme allows you to move that to the top level by specifying BookSection="*" in the params section – see the theme configuration docs for more information.

In addition, you can specify a path of the originating repository in source in order to only have a subset of a repository. This might be quite a nice way of consolidating docs from multiple repositories for example. In this case we want the entire repository so have just specified ..

What’s next

Given that you can use hugo modules to mount any of the seven component types, the possibilities seem endless. We could have a centralised theme which is mounted into multiple documentation sites; we could use centralised assets for consistency between sites whilst making it easier to maintain; we could centralise all our shortcodes for use across those sites etc..

In addition, I’d like to investigate the possibility of extracting information from alternative sources for inclusion into the site for those teams that would be less familiar with maintaining a github repository.

The example used in this post is available at https://github.com/darrenparkinson/hugo-handbook.