Tech docs template
The project consists of 3 repositories:
- alphagov/tech-docs-template: the middleman site generator used to generate new sites
- alphagov/tech-docs-gem: the gem used by generated sites to include HTML, CSS and JS
- alphagov/tech-docs-manual: the repo that generates the documentation you’re looking at now
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
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.
You can configure the site using
config/tech-docs.yml. See the PaaS tech docs for an example.
These are all the available options:
Tracking ID from Google Analytics
Your repository. Required if show_contribution_banner is true.
Adds a Google Site Verification code to the meta tags.
Right hand side navigation.
header_links: Documentation: /
Host to use for canonical URL generation (without trailing slash).
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.
Prevent robots from indexing (e.g. whilst in development)
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
The service name in the header.
service_name: "Platform as a Service"
What the service name in the header links to.
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.
“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.
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.
If the page needs to be reviewed, we show a red box saying the page might not be accurate.
--- 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.
The layout of the page.
--- layout: core ---
There are 2 available page layouts.
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
--- layout: layout --- # The title ### A subheader #### A h3 subheader ### Another subheader
Will generate a page with the headings from the content in the sidebar.
If you want more control about the layout, use
core layout. This allows you to specify the sidebar manually with a
--- 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.
Any paths of pages that should redirect to this page.
--- old_paths: - /some-old-page.html ---
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" ---
The browser title of the page.
--- title: My beautiful page ---
The page that should be highlighted as ‘active’ in the navigation.
--- parent: shaving-yaks.html ---
Developing the template
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.
This project is in active use by:
- GDS Way (GitHub repo)
- GOV.UK Content API (GitHub repo)
- GOV.UK Developer docs (GitHub repo)
- GOV.UK Pay (GitHub repo)
- GOV.UK Platform as a Service (GitHub repo)
- GOV.UK Registers (GitHub repo)
- Reliability Engineering (GitHub repo)
- GOV.UK Notify (GitHub repo)