Skip to main content
  1. Home
  2. Repos

Repository: govuk-developer-docs

📖 Tech docs for everyone working on GOV.UK

GitHub
govuk-developer-docs
Ownership
#govuk-developers
Category
Utilities

README

👉 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

List markup

The Tech Docs template uses Redcarpet as its Markdown engine, which is quite particular about how to nest lists and different types of content within them. The gem has an infrequent release cadence and many known issues with list parsing.

A different number of line breaks and spaces (for indentation) are needed for different types/combinations of content, and existing code is not guaranteed to be ‘correct’ as far as Redcarpet is concerned, so be sure to pay attention to how lists get rendered by running the app locally or deploying to integration before merging changes. Formatters like Prettier are unlikely format lists in a Redcarpet-compliant way.

Examples of addressing list parsing issues:

Licence

MIT License