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 [external link] 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 [external link].

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](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.

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.