Tech docs template Beta
Table of contents

Publish your documentation

To publish your documentation, you must:

  • push your documentation to the remote GitHub repo
  • deploy your site

Push documentation to GitHub

These instructions assume that you have documentation changes ready to push to GitHub.

To push your documentation changes to GitHub for the first time, you must:

  • create local and remote GitHub repos
  • commit all changes in the local repo
  • link the local repo to the remote repo
  • push the staged commit to the remote repo

Create local and remote GitHub repos

  1. Create a remote empty repo in your organisation on GitHub.

  2. Create a new local documentation repo if required.

Commit all changes in the local repo

  1. Go to the local repo directory in the command line.

  2. Make the created local repo into a Git repo:

    git init
  3. If applicable, add all files in the local repo and stage them for commit:

    git add .
  4. Commit the staged files:

    git commit -m "COMMIT-MESSAGE"`

    where COMMIT-MESSAGE is the message describing the commit.

  1. Go to the remote repo in GitHub.

  2. Select the Clone or download button.

  3. Select either Use HTTPS or Use SSH.

  4. Select the copy button.

  5. In the command line, link the local repo to the remote repo:

    git remote add origin REMOTE-REPO-URL
  6. Verify the remote repo:

    git remote -v

Push the staged commit to the remote repo

Push the changes in your local repo to the remote repo:

git push -u origin master

You have now created a remote documentation repo on GitHub.

For more information, refer to Adding an existing project to GitHub.

Deploy your site

The Tech Docs Template is built on Middleman, which is a static site generator. You can therefore deploy your site anywhere that supports static sites.

Use the GOV.UK PaaS

We recommend that government services use the GOV.UK PaaS to deploy documentation sites built with the Tech Docs Template. This is also free of charge for government services.

GitHub Pages

With some modification, you can also deploy your site with GitHub Pages, but we do not support this. To do this, you could for example use the [middleman-gh-pages] tool](, which we do not support. We also cannot guarantee that all features of the tool will work if you deploy your site with GitHub Pages.

Add basic authentication

There are many ways to add basic authentication to your documentation site.

The following instructions apply if you want to deploy your documentation site on the GOV.UK PaaS or another platform using the Cloud Foundry open source cloud application platform.

This method relies on adding a Staticfile.auth file to the build folder because building the documentation doesn’t automatically add the Staticfile.auth file. If you added Staticfile.auth once and run the build command again, the file will disappear. You need to add Staticfile.auth again to enable basic authentication for the new build.

  1. In the command line, navigate to your local documentation repo.

  2. If required, run bundle exec middleman build to create a build folder.

  3. Create a new Staticfile.auth file in the build folder.

  4. Go to the Htpasswd Generator.

  5. Complete the Username and Password fields, and select Create .htpasswd file.

  6. Copy the generated username and password hash into the Staticfile.auth file and save.

  7. Deploy your documentation site in line with your normal process.

Current published technical documentation

Organisation Title Location GitHub repo
Ministry of Justice Cloud platform user guide
HMRC VAT (MTD) end-to-end service guide
HMRC Self Assessment end-to-end service guide
GDS GOV.UK Platform as a Service
GDS GDS Reliability Engineering
GDS GOV.UK Registers

Continuous integration

The GOV.UK PaaS documentation explains how to set up continuous integration (CI) with Travis and Jenkins. We recommend this method for documentation sites built using the Tech Docs Template.