{"id":13878602,"url":"https://github.com/alphagov/govuk-developer-docs","last_synced_at":"2025-10-20T04:35:50.560Z","repository":{"id":37430894,"uuid":"57145363","full_name":"alphagov/govuk-developer-docs","owner":"alphagov","description":"📖 Tech docs for everyone working on GOV.UK","archived":false,"fork":false,"pushed_at":"2025-05-08T19:23:10.000Z","size":48166,"stargazers_count":121,"open_issues_count":30,"forks_count":31,"subscribers_count":62,"default_branch":"main","last_synced_at":"2025-05-08T22:49:40.256Z","etag":null,"topics":["container","govuk","tech-docs-template"],"latest_commit_sha":null,"homepage":"https://docs.publishing.service.gov.uk","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alphagov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-04-26T16:43:08.000Z","updated_at":"2025-05-08T10:56:37.000Z","dependencies_parsed_at":"2023-09-26T16:56:18.950Z","dependency_job_id":"3dca0d5c-11bd-4e97-975b-70bbeae3d604","html_url":"https://github.com/alphagov/govuk-developer-docs","commit_stats":null,"previous_names":[],"tags_count":348,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk-developer-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk-developer-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk-developer-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk-developer-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alphagov","download_url":"https://codeload.github.com/alphagov/govuk-developer-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253160827,"owners_count":21863624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","govuk","tech-docs-template"],"created_at":"2024-08-06T08:01:54.423Z","updated_at":"2025-10-20T04:35:45.512Z","avatar_url":"https://github.com/alphagov.png","language":"HTML","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# GOV.UK Developer Docs\n\n👉 https://docs.publishing.service.gov.uk/\n\nThis is a static site generated with Middleman, using [alphagov/tech-docs-template](https://github.com/alphagov/tech-docs-template).\n\nSome 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`.\n\n## Run the app locally\n\nRun govuk-developer-docs either inside or outside govuk-docker, configuring its behaviour with the ENV variables below.\n\n### ENV variables\n\n- `GITHUB_TOKEN=\u003cyour private token\u003e` - 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](https://github.com/settings/tokens/new) (the token doesn't need any scopes).\n- `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.\n- `NO_CONTRACTS=true` - [recommended setting](https://github.com/alphagov/govuk-developer-docs/commit/4b624a72761490c8e9b99a1aa7a10371415381e6) for speeding up the site build process\n\n### Run with govuk-docker\n\ngovuk-docker doesn't have great support for passing ENV vars into the application startup. You'll need to [edit the docker-compose.yml](https://github.com/alphagov/govuk-docker/blob/ed98d3547708286f534598c78fb5c57ee3c8d112/projects/govuk-developer-docs/docker-compose.yml#L12-L17) 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:\n\n```yml\n   environment:\n      GITHUB_TOKEN: \"\u003cfill it in\u003e\"\n```\n\n1. In govuk-docker:\n  1. Edit `govuk-docker/projects/govuk-developer-docs/docker-compose.yml` as above\n  1. [make the project](https://docs.publishing.service.gov.uk/repos/govuk-docker.html#usage)\n1. In govuk-developer-docs:\n  1. Install the dependencies (`govuk-docker-run bundle install`)\n  1. Run the application (`govuk-docker-up`)\n  1. 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.\n1. Visit \u003chttp://govuk-developer-docs.dev.gov.uk/\u003e\n\n### Run without govuk-docker\n\n1. Install the dependencies (`bundle install`)\n1. Start up the site with `./startup.sh` (passing ENV vars on the CLI if necessary)\n\n## Building the project, and running tests\n\nIf 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):\n\n```sh\nNO_CONTRACTS=true bundle exec middleman build --verbose\n```\n\nTo run the tests:\n\n```\nbundle exec rake\n```\n\n## Update to the latest Tech Docs template\n\n```sh\nbin/update\n```\n\n## Deployment\n\nWe host GOV.UK Developer Docs as a static site on GitHub Pages. The [ci.yml] GitHub Actions workflow updates the site automatically:\n\n- when a PR is merged to the default branch\n- on an hourly schedule, to pick up changes to docs included from other repos\n\n## List markup\n\nThe Tech Docs template uses Redcarpet as its [Markdown engine][], which is quite\nparticular about how to nest lists and different types of content within them.\nThe gem has an infrequent release cadence and many known [issues with list\nparsing][].\n\nA different number of line breaks and spaces (for indentation) are needed for\ndifferent types/combinations of content, and existing code is not guaranteed to\nbe 'correct' as far as Redcarpet is concerned, so be sure to pay attention to\nhow lists get rendered by running the app locally or deploying to integration\nbefore merging changes. Formatters like Prettier are unlikely format lists in a\nRedcarpet-compliant way.\n\nExamples of addressing list parsing issues:\n\n- [7566684][]\n- [897595e][]\n\n[7566684]: https://github.com/alphagov/govuk-developer-docs/commit/75666849c773549572decedf883cea1e8f1743ee\n[897595e]: https://github.com/alphagov/govuk-developer-docs/commit/897595e7704e96fc302a58b913e7b3f5a0594953\n[issues with list parsing]:\n  https://github.com/vmg/redcarpet/issues?q=is%3Aissue%20state%3Aopen%20list\n[Markdown engine]:\n  https://github.com/alphagov/tech-docs-gem/blob/3720daadaf3f8e4693fe74c1c591493fe567b7fc/lib/govuk_tech_docs.rb#L56\n\n## Licence\n\n[MIT License](LICENCE)\n\n[ci.yml]: /.github/workflows/ci.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphagov%2Fgovuk-developer-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falphagov%2Fgovuk-developer-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphagov%2Fgovuk-developer-docs/lists"}