Table of contents

Tech docs template

The Tech docs template is a middleman template that you can use to build technical documentation using a GOV.UK style.

Screenshot of Example Documentation

The project consists of 3 repositories:

Create a new site

You’ll need middleman installed, and its dependencies (Ruby). If you have Ruby v2.2.2 or newer installed you should just be able to run gem install middleman. Installing or updating Ruby is outside the scope of this README.

From the command line run the following commands, substituting my-new-project for the name of your new project:

middleman init my-new-project -T alphagov/tech-docs-template

This will run an interactive prompt where you can set basic configuration for your project.

After installing, you can further customise your site.

Update a site

If you want to upgrade to the latest version run the following:

bundle update govuk_tech_docs

This will make the site use the latest version of the govuk_tech_docs gem.

The CHANGELOG in the gem should tell you what changed.

Configuration options

You can configure the site using config/tech-docs.yml. See the PaaS tech docs for an example.

These are all the available options:

ga_tracking_id

Tracking ID from Google Analytics

ga_tracking_id: UA-XXXX-Y

github_repo

Your repository. Required if show_contribution_banner is true.

github_repo: alphagov/example-repo

google_site_verification

Adds a Google Site Verification code to the meta tags.

google_site_verification: TvDTuyvdstyusadrCSDrctyd

Right hand side navigation.

Example:

header_links:
  Documentation: /

host

Host to use for canonical URL generation (without trailing slash).

Example:

host: https://docs.cloud.service.gov.uk

max_toc_heading_level

Table of contents depth – how many levels to include in the table of contents. If your ToC is too long, reduce this number and we’ll only show higher-level headings.

max_toc_heading_level: 6

phase

phase: "Beta"

prevent_indexing

Prevent robots from indexing (e.g. whilst in development)

prevent_indexing: false

redirects

A list of redirects, from old to new location. Use this to set up external redirects or if setting old_paths in the frontmatter doesn’t work.

redirects:
  /old-page.html: https://example.org/something-else.html
  /another/old-page.html: /another/new-page.html

service_name

The service name in the header.

Example:

service_name: "Platform as a Service"

What the service name in the header links to.

default: ’/’

service_link: "/"

show_contribution_banner

Show a block at the bottom of the page that links to the page source, so readers can easily contribute back to the documentation. If turned on github_repo is required.

Off by default.

show_contribution_banner: true
github_repo: alphagov/example-repo

Whether to show the GOV.UK crown logo.

default: true

show_govuk_logo: true

Frontmatter

“Frontmatter” allows page-specific variables to be included at the top of a template using YAML. For a general introduction on frontmatter, see the Middleman frontmatter docs.

last_reviewed_on and review_in

These attributes determine the date when the page needs to be reviewed next.

If the page doesn’t need to be reviewed, we show a blue box with the last-reviewed date, when it needs review again, and the owner.

Not expired page

If the page needs to be reviewed, we show a red box saying the page might not be accurate.

Expired page

Example:

---
last_reviewed_on: 2018-01-18
review_in: 6 weeks
---

You can use this in combination with owner_slack to set an owner for the page.

layout

The layout of the page.

---
layout: core
---

There are 2 available page layouts.

The layout layout (default)

By default, pages will use the layout layout. This layout will parse the page and generate a sidebar with a table of contents consisting of each h2, h3, h4 heading.

---
layout: layout
---

# The title

### A subheader

#### A h3 subheader

### Another subheader

Will generate a page with the headings from the content in the sidebar.

Layout layout

core layout

If you want more control about the layout, use core layout. This allows you to specify the sidebar manually with a content_for block.

---
layout: core
---

<% content_for :sidebar do %>
  You can put anything in the sidebar.
<% end %>

This page has a configurable sidebar that is independent of the content.

Core layout

old_paths

Any paths of pages that should redirect to this page.

Example:

---
old_paths:
  - /some-old-page.html
---

owner_slack

The Slack username or channel of the page owner. This can be used to appoint an individual or team as responsible for keeping the page up to date.

---
owner_slack: "#operations-teams"
---

title

The browser title of the page.

---
title: My beautiful page
---

parent

The page that should be highlighted as ‘active’ in the navigation.

---
parent: shaving-yaks.html
---

Developing the template

Local development

Refer to the readme of tech-docs-template if you intend to make changes to the generator.

Refer to the readme of the gem if you intend to work on the gem.

Active users

This project is in active use by:

In development: