Skip to main content

Structure your documentation

When you create a new project, that project has a source folder containing:

  • a documentation/ content file
  • an file

The file contains a partial that refers to the documentation/ content file.

To structure your documentation, add content directly to the file.

For example, an file with the following sections:

  • an introduction
  • a “Who this documentation is for” section
  • a “Set up the API client” section

That file could look like this:

title: Tech Docs

# Introduction


# Who is this documentation for?


# Set up the API client


When you build or preview your documentation site with this, the site will be a single page site with the following structure:

  • Introduction
  • Who is this documentation for?
  • Set up the client

Build a multipage documentation site

You can create a technical documentation site that splits its content across multiple pages.

This is suitable for documentation sites that have too much content for the single page format.

Examples include the:

You should use the search feature with multipage documentation sites.

Amend the tech-docs.yml file

Add the following code to your project’s config/tech-docs.yml file if necessary:

multipage_nav: true

Create the multipage folder structure

Each folder inside the source folder represents one documentation page.

For each page, create a content folder and put an file into that folder. This file is the content file.

Amend the files

Add a weight argument and value to the frontmatter of each file. This builds the structure of the multipage documentation.

For example:

title: Product Technical Documentation


title: Product Technical Documentation
weight: 10

Higher weights mean the content is lower down in the documentation hierarchy. A way to remember this is to think “heavier pages sink to the bottom”.

Make sure every individual page starts with an H1 heading.

Nest pages within pages (optional)

You can nest pages within each other.

To do this, create content folders inside content folders with content files.

Each file inside a nested folder must have a weight value that preserves the overall hierarchy both within the nested content and compared to the other non-nested content.

An example of this content structure is the GOV.UK Pay technical documentation on switching to live:

This page was last reviewed on 1 July 2020. It needs to be reviewed again on 1 July 2021 by the page owner #gds-technical-writing .
This page was set to be reviewed before 1 July 2021 by the page owner #gds-technical-writing. This might mean the content is out of date.