ADR-0004 Use Hugo

Date2021-05-11
StatusAccepted

Context

We need to publish technical documentation for the project as it progresses (for example, architecture diagrams, use case details, and architecture decision records). We should make it as easy as possible for developers to write documentation and keep it up to date.

In ADR-0003 we describe how we will use GitLab to host source code repositories. If we choose a text-based format for our documentation, this can also be maintained in a git repository. Markdown is one such format: it is a simple and easily-readable plain text format that can be transformed to structured HTML.

Hugo is a popular static site generator that uses templates to transform a collection of Markdown files, images, and other media into a tree of static files that can be served by any web server.

Decision

We will use the Hugo static site generator.

We will host technical documentation on GitLab Pages.

We will configure a GitLab CI pipeline to regenerate the site and publish changes when they are pushed to the main branch.

We will configure a GitLab CI pipeline to generate a test version of the site for each merge request, to facilitate review.

Consequences

Maintaining documentation in a plain text format in a git repository makes it easy for developers to write and update using familiar tools.

Changes can be made to the live site by making a merge request against the main branch and merging as soon as they have been reviewed.

Collaborators can run hugo locally to test changes before pushing to the shared repository.