Skip to main content
Table of contents

Build a single page documentation site

You can create a technical documentation site that contains all of its content in a single page. An example is the GOV.UK Notify Java documentation.

This is suitable for documentation sites that have do not have a lot of content, and do not need to have topics split into individual pages.

Organise content files

  1. Create the content files for your documentation site.

  2. Amend your content files to ready them for your documentation site.

  3. Save your content files inside your documentation repo in your desired hierarchy.

Build your documentation site’s structure

  1. Go to the source folder in your documentation repo.

  2. Select the index.html.md.erb file.

  3. Amend the index.html.md.erb file.

    You can either add a partial line that references each content file that makes up your overall documentation site, or add the content into the index.html.md.erb file directly.

    The .html.md.erb files must not have the same name as the folders that the .html.md.erb files use partials refer to.

    For example, you cannot have a support.html.md.erb file that contains the partial partial 'support/contact_us' %>.

Add partial lines

In this example, you have three content files:

  • an introduction named index.md in the documentation folder
  • a “Who is this documentation for?” section named who-docs.md in the documentation/introduction folder
  • a “Set up the API client” section named set_up_client in the documentation/introduction folder

The index.html.md.erb file would look like this:

---
title: "GOV.UK Technical Documentation"
---

PARTIAL
PARTIAL
PARTIAL

This index.html.md.erb will build a documentation site with the following structure:

  • Introducution
  • Who is this documentation for?
  • Set up the client
This page was last reviewed on 3 October 2019. It needs to be reviewed again on 4 October 2019 by the page owner #docs-repos .
This page was set to be reviewed before 4 October 2019 by the page owner #docs-repos. This might mean the content is out of date.