Skip to main content

Deploy and host your documentation 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 template will work if you deploy your site with GitHub Pages.

The Ministry of Justice cloud platform documentation uses GitHub Pages.

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.

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.

This page was last reviewed on 1 July 2020. It needs to be reviewed again on 1 July 2021 by the page owner #gds-technical-writing .
This page was set to be reviewed before 1 July 2021 by the page owner #gds-technical-writing. This might mean the content is out of date.