Tech Docs Template
This repo is the template used to generate new sites. The generated site uses HTML, CSS, JS and images from the tech docs 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)
- 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.
Creating a new documentation project
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.
In order to configure things like the header, edit
Updating a project to use the latest template
In most cases you can update your project to the latest template by running:
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 and if you have to update any of your files. If that is the case, run:
middleman init . -T alphagov/tech-docs-template
If you have made any changes to the layout or any of the assets you will be prompted to resolve any conflicts, at which point you can view a diff between your version and the latest version.
If you make changes to the template you can create a test site with this command. Make sure that you've committed your changes first, because Middleman works with Git.
bundle install bundle exec middleman init tmp/test-run -T file://$(pwd) cd tmp/test-run bundle exec middleman server
Your generated site should appear on http://localhost:4567.