GOV.UK Developer Docs

👉 https://docs.publishing.service.gov.uk/

This is a static site generated with Middleman, using alphagov/tech-docs-template.

Some of the files (like the CSS, javascripts and layouts) are managed in the template and are not supposed to be modified here. Any project-specific Ruby code needs to go into /app.

Run the app locally

Run govuk-developer-docs either inside or outside govuk-docker, configuring its behaviour with the ENV variables below.

ENV variables

• GITHUB_TOKEN=<your private token> - token to use to make authenticated requests to GitHub's API. Authenticated requests have a much higher rate limit. You will need to specify a GITHUB_TOKEN if you want to build the entire Developer Docs site. Create the token on GitHub (the token doesn't need any scopes).
• SKIP_PROXY_PAGES=true - avoid fetching remote 'docs/' for each repo (i.e. just build the docs that live within govuk-developer-docs itself). You can use this if you don't have a GITHUB_TOKEN or if you don't care about including the remote docs.
• NO_CONTRACTS=true - recommended setting for speeding up the site build process

Run with govuk-docker

govuk-docker doesn't have great support for passing ENV vars into the application startup. You'll need to edit the docker-compose.yml to add the necessary ENV vars (e.g. GITHUB_TOKEN) under the environment property for both the govuk-developer-docs-app and govuk-developer-docs-lite groups, eg:

   environment:
      GITHUB_TOKEN: "<fill it in>"

1. In govuk-docker:
2. Edit govuk-docker/projects/govuk-developer-docs/docker-compose.yml as above
3. make the project
4. In govuk-developer-docs:
5. Install the dependencies (govuk-docker-run bundle install)
6. Run the application (govuk-docker-up)
7. Wait until all the GitHub API calls have completed (you'll see Inspect your site configuration at in the output). This can take a few minutes.
8. Visit http://govuk-developer-docs.dev.gov.uk/

Run without govuk-docker

1. Install the dependencies (bundle install)
2. Start up the site with ./startup.sh (passing ENV vars on the CLI if necessary)

Building the project, and running tests

If you just want to create the site (a build/ directory containing a set of HTML files), but not actually start up the application, you can do so as follows (again, the ENV variables described above apply here too):

NO_CONTRACTS=true bundle exec middleman build --verbose

To run the tests:

bundle exec rake

Update to the latest Tech Docs template

bin/update

Deployment

We host GOV.UK Developer Docs as a static site on GitHub Pages. The ci.yml GitHub Actions workflow updates the site automatically:

• when a PR is merged to the default branch
• on an hourly schedule, to pick up changes to docs included from other repos

Licence

MIT License