Structure your documentation
When you create a new project, that project has a source folder containing:
index.html.md.erb file contains a
partial that refers to the
documentation/index.md content file.
To structure your documentation, add content directly to the
For example, an
index.html.md.erb file with the following sections:
- an introduction
- a “Who this documentation is for” section
- a “Set up the API client” section
index.html.md.erb file could look like this:
--- title: Tech Docs --- # Introduction CONTENT # Who is this documentation for? CONTENT # Set up the API client CONTENT
When you build or preview your documentation site with this
index.html.md.erb, the site will be a single page site with the following structure:
- 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:
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
index.html.md.erb file into that folder. This
index.html.md.erb file is the content file.
Amend the index.html.md.erb files
Add a weight argument and value to the frontmatter of each .html.md.erb file. This builds the structure of the multipage documentation.
--- 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
index.html.md.erb content files.
.html.md.erb 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: