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
Create a remote empty repo in your organisation on GitHub.
Create a new local documentation repo if required.
Commit all changes in the local repo
Go to the local repo directory in the command line.
Make the created local repo into a Git repo:
If applicable, add all files in the local repo and stage them for commit:
git add .
Commit the staged files:
git commit -m "COMMIT-MESSAGE"`
COMMIT-MESSAGEis the message describing the commit.
Link the local repo to the remote repo
Go to the remote repo in GitHub.
Select the Clone or download button.
Select either Use HTTPS or Use SSH.
Select the copy button.
In the command line, link the local repo to the remote repo:
git remote add origin REMOTE-REPO-URL
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.
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 [
tool](https://github.com/edgecase/middleman-gh-pages), 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.
In the command line, navigate to your local documentation repo.
If required, run
bundle exec middleman buildto create a
Create a new
Staticfile.authfile in the
Go to the Htpasswd Generator.
Complete the Username and Password fields, and select Create .htpasswd file.
Copy the generated username and password hash into the
Staticfile.authfile and save.
Deploy your documentation site in line with your normal process.
Current published technical documentation
|Ministry of Justice||Cloud platform user guide||https://user-guide.cloud-platform.service.justice.gov.uk/||https://github.com/ministryofjustice/cloud-platform-user-guide|
|HMRC||VAT (MTD) end-to-end service guide||https://developer.service.hmrc.gov.uk/guides/vat-mtd-end-to-end-service-guide/||https://github.com/hmrc/vat-service-guide|
|HMRC||Self Assessment end-to-end service guide||https://developer.service.hmrc.gov.uk/guides/self-assessment-end-to-end-service-guide/||https://github.com/hmrc/self-assessment-end-to-end-service-guide|
|GDS||GOV.UK Platform as a Service||https://docs.cloud.service.gov.uk/#gov-uk-platform-as-a-service||https://github.com/alphagov/paas-tech-docs|
|GDS||GDS Reliability Engineering||https://reliability-engineering.cloudapps.digital/||https://github.com/alphagov/reliability-engineering|
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.