Tech Docs Template
The Tech Docs Template is a Middleman template that you can use to build technical documentation using a GOV.UK style.
This repo is the template used to generate new sites. The generated site uses HTML, CSS, JS and images from the tech docs gem.
You’re welcome to use the template even if your service isn’t considered part of GOV.UK, but your site or service must not:
- identify itself as being part of GOV.UK
- use the crown or GOV.UK logotype in the header
- use the GDS Transport typeface
- suggest that it’s an official UK government website if it’s not
Before you start
To use the Tech Docs Template you need:
To create a new project using the Tech Docs Template, run:
middleman init PROJECT_NAME -T alphagov/tech-docs-template
PROJECT_NAME is the name of your new project.
This command creates a minimal functional website using the Tech Docs Template.
Preview your website locally
To preview your new website locally, navigate to your project folder and run:
bundle exec middleman server
http://localhost:4567 in your browser. Any content changes you make to your website will be updated in real time.
To shut down the Middleman instance running on your machine, use
If you make changes to the
config/tech-docs.yml configuration file, you need to restart Middleman to see the changes.
Configure your website
middleman init command creates a minimal website with basic configuration.
You can change your website's configuration by editing the
You can set page-specific options by editing the page's frontmatter.
You can add content by editing the
index.html.md.erb file. These files support content in:
Any file in the
source folder ending in
.html.md.erb produces a separate page for your website.
To publish your website, you need to:
- build the HTML pages
- host your website
- decide how to push changes to your website
To build the HTML pages from content in your
source folder, run:
bundle exec middleman build
Every time you run this command, the
build folder gets generated from scratch. This means any changes to the
build folder that are not part of the build command will get overwritten.
There are many options for hosting and pushing changes to your website, so it's worth considering user needs and constraints before making a choice.
bundle update to make sure you're using the most recent Ruby gem versions.
bundle exec middleman build --verbose to get detailed error messages to help with finding the problem.
Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.