Skip to main content

Configure your documentation site

You can configure your documentation site by editing the config/tech-docs.yml file in a text editor.

When you create your documentation project, the template creates a tech-docs.yml file with the following default settings:

# Host to use for canonical URL generation (without trailing slash)
host:

# Header-related options
show_govuk_logo: true
service_name: My First Service
service_link: https://www.larry-the-cat.service.gov.uk
phase: Beta

# Links to show on right-hand-side of header
header_links:
  About: https://www.larry-the-cat.service.gov.uk
  Get Started: https://www.larry-the-cat.service.gov.uk/get-started
  Documentation: /
  Support: https://www.larry-the-cat.service.gov.uk/support

# Enables search functionality. This indexes pages only and is not recommended for single-page sites.
enable_search: false

# Tracking ID from Google Analytics (for example UA-XXXX-Y)
ga_tracking_id:

# Enable multipage navigation in the sidebar
multipage_nav: false

# Enable collapsible navigation in the sidebar
collapsible_nav: false

# 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

# Prevent robots from indexing (for example whilst in development)
prevent_indexing: false

show_contribution_banner: true
github_repo: alphagov/YOUR_REPO
github_branch: main
Warning All of these settings are optional. However, you should enable or disable settings to increase the usability of your documentation or because of best practice.

You must wrap a value in quotes if it contains a colon, unless the value is a URL. For example:

description: "GDS: My amazing documentation"

If you are not sure which settings to enable or disable, contact the Government Digital Service (GDS) technical writing team.

See the Platfom as a Service (PaaS) tech docs config file for an example tech-docs.yml file.

Default settings

The following section defines the default settings in the tech-docs.yml file, and tells you how to enable and disable them.

host

Defines the host used for canonical URL generation (without trailing slash).

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

Enables and disables the GOV.UK crown logo in the top left corner of the site. Defaults to true.

show_govuk_logo: true

service_name

Defines the service name in the header. Defaults to “My First Service” if you do not define it when creating your project.

service_name: "Platform as a Service"

What the service name in the header links to. Defaults to “https://www.larry-the-cat.service.gov.uk” if you do not define it when creating your project.

service_link: "https://www.larry-the-cat.service.gov.uk"

phase

Defines the phase of the service that the documentation is attached to. Defaults to “Beta”.

phase: "Beta"

Populates the top right banner navigation with links. You can change the number and text of the default links. For example:

header_links:
  About: https://www.payments.service.gov.uk/#main
  Get started: https://www.payments.service.gov.uk/getstarted/
  Documentation: /
  Support: https://www.payments.service.gov.uk/support/
  Sign In: https://selfservice.payments.service.gov.uk/login

Enables search functionality. This indexes pages only, and you should only enable this if you have a multipage documentation site.

enable_search: true

ga_tracking_id

Insert the Google Analytics tracking ID to enable Google Analytics.

If you use Google Analytics, you must follow the guidance on working with cookies in the GOV.UK Service Manual.

Speak to your technical or engineering community to find out how to enable Google Analytics for your documentation and get a tracking ID.

ga_tracking_id: UA-XXXX-Y

multipage_nav

Enable multipage navigation in the sidebar. Defaults to false.

multipage_nav: false

collapsible_nav

Enable collapsible navigation in the sidebar. Defaults to false.

collapsible_nav: false

max_toc_heading_level

States how many heading levels to include in the table of contents (ToC). Can take values between 1 and 6. Use a lower number to reduce the length of the ToC. Best practice is to not go higher than 3.

max_toc_heading_level: 6

prevent_indexing

Prevent robots from indexing.

prevent_indexing: false

show_contribution_banner

Enable a banner at the bottom of the page that links to the page source, so readers can easily contribute back to the documentation. Defaults to “true”.

If you enable this setting, you must also enable the github_repo setting.

show_contribution_banner: true

github_repo

Your documentation project’s GitHub repository. You must enable this if you have enabled show_contribution_banner.

github_repo: alphagov/example-repo

github_branch

Your project’s GitHub default branch name. You can change this if your default branch is not named main.

github_branch: source

Note: When creating a project using the template this is set to “main”, but if this setting is not present the default is currently “master”. This will change in a future major release.

Additional settings

You can enable and disable the following additional settings in the tech-docs.yml file.

api_path

Define a path to an Open API V3 spec file. This can be a relative file path or a URI to a raw file.

api_path: ./source/pets.yml

Defines links to show in the site footer.

footer_links:
  Accessibility: /accessibility

full_service_name

The full service name. Include “GOV.UK” if appropriate.

full_service_name: "GOV.UK Pay"

google_site_verification

Adds a Google Site verification code to the meta tags.

google_site_verification: TvDTuyvdstyusadrCSDrctyd

“owner_slack_workspace” and “default_owner_slack”

These attributes are used to specify the owner of a page. See page expiry for more information.

redirects

A list of redirects from an old location to a new location.

Use this to set up external redirects or if setting old_paths in the frontmatter does not work.

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

show_expiry

Enables and disables displaying a red banner when the page needs to be reviewed.

If not present or set to true, the red banner will display when the page needs to be reviewed. This is the default behaviour.

If set to false, the red banner will not display when the page needs to be reviewed.

See page expiry for more information.

show_review_banner

Enables or disables displaying the page review banner, regardless of whether the page needs to be reviewed or not.

If not present or set to true, the banner will always be displayed on the page. This is the default behaviour.

If set to false, the banner will not be displayed.

See page expiry for more information.

source_urls

If you’ve enabled the contribution banner, set source_urls to the URLs you want the contribution banner to link to.

By default, “Report issue” links to raising a GitHub issue, but by modifying the report_issue_url, it can link to an email address or another page.

source_urls:
  report_issue_url: mailto:support@example.com

You can configure the Technical Documentation Template (TDT) to build your documentation site using relative links to pages and assets.

To use relative links, add the following lines to your config.rb file:

set :relative_links, true
activate :relative_assets
This page was last reviewed on 1 July 2020. It needs to be reviewed again on 1 July 2021 .