Build GOV.UK style static sites with Hugo

This site demonstrates how the govuk-hugo theme works.

govuk-hugo is a theme for the Hugo static site builder.

Getting started

To use govuk-hugo, install Hugo as per the getting started advice and then create a new site.

If creating from scratch (i.e. without an existing directory) the following code will create a Hugo site in the folder called SITEDIR:

1
$ hugo new site SITEDIR -f "yaml"

You can initialise an existing directory (e.g. if you’ve already created an empty git repo) as a Hugo site by navigating to the directory and then forcing a new site to be built:

1
2
$ cd SITEDIR
$ hugo new site . --force -f "yaml"

Note that YAML is preferred for the format of config files, all documentation for govuk-hugo will use YAML. TOML (Hugo’s default) should work, but is not supported and has not been tested.

Add the govuk-hugo theme

Add as a git clone/submodule, as the theme is under active development it is recommended that you use git to add the theme so that you can easily get updates.

If your hugo site is in its own git repo then add as a submodule:

1
$ git submodule add https://github.com/co-analysis/govuk-hugo.git themes/govukhugo

If you hugo site is not a git repo then clone the theme:

1
$ git clone https://github.com/co-analysis/govuk-hugo.git themes/govukhugo

You can also manually add the theme, this is not recommended as it will be less easy for you to track updates:

  1. Download the govuk-hugo repo’s zip file
  2. Create a govukhugo folder inside the themes folder
  3. Extract the zip file and copy the files and folders into the themes/govukhugo folder

Configure

To apply the govuk-hugo theme, your config.yaml file should look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
baseURL: https://your.site/
languageCode: en-gb
title: Your site
theme: govukhugo
publishDir: docs
canonifyurls: true

pygmentsUseClasses: true

markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    lineAnchors: ""
    lineNoStart: 1
    lineNos: true
    lineNumbersInTable: true
    noClasses: true
    style: github
    tabWidth: 2


params:
  govuk: false
  logotext: AAA
  product: Your site
  phase: alpha
  feedbackurl: https://your.site/feedback
  builtby: Your Team
  builtbyurl: https://your.org/

If deploying to GitHub Pages you must set publishDir: docs and canonifyurls: true.

Set unsafe: true if you want to be able to use raw HTML in in markdown documents.

Unless you are deploying to a .gov.uk subdomain you should set govuk: false - this ensures you do not use GOV.UK’s New Transport font, nor use the GOV.UK crown in the header and as the favicon, these are only permitted for use on .gov.uk subdomains.

You should provide a service acronym using logotext: AAA - this should be capitalised. If deploying to a .gov.uk domain you should set this as logotext: GOV.UK.

You can provide a product name using product: Product Name which will provide the product name in the header. If a product name is not provided the title specified at the top of the config.yaml file will be used.

To add a GOV.UK style “phase” banner set phase: alpha or phase: beta in the params. You must also provide a feedback URL using feedbackurl: https://your.site/feedback.

You can add a “built by” reference by setting builtby: Your Team. You must also provide a URL to your team or organisation’s main website using builtbyurl: https://your.org/