{"id":27998331,"url":"https://github.com/alphagov/paas-tech-docs","last_synced_at":"2025-05-08T22:52:32.415Z","repository":{"id":37972583,"uuid":"76549592","full_name":"alphagov/paas-tech-docs","owner":"alphagov","description":"Technical documentation for GOV.UK PaaS","archived":false,"fork":false,"pushed_at":"2025-02-27T00:44:49.000Z","size":3377,"stargazers_count":12,"open_issues_count":14,"forks_count":21,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-05-08T22:52:23.734Z","etag":null,"topics":["documentation","paas","reliability-engineering","tech-docs-template"],"latest_commit_sha":null,"homepage":"https://docs.cloud.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":"security.txt.html","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-15T10:23:28.000Z","updated_at":"2024-11-21T10:52:11.000Z","dependencies_parsed_at":"2023-12-21T19:16:48.181Z","dependency_job_id":"eb876292-55c7-4724-a4d6-15431b89adb0","html_url":"https://github.com/alphagov/paas-tech-docs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fpaas-tech-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fpaas-tech-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fpaas-tech-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fpaas-tech-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alphagov","download_url":"https://codeload.github.com/alphagov/paas-tech-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":["documentation","paas","reliability-engineering","tech-docs-template"],"created_at":"2025-05-08T22:52:30.454Z","updated_at":"2025-05-08T22:52:32.408Z","avatar_url":"https://github.com/alphagov.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GOV.UK PaaS Technical Documentation\n\nThis is the new technical documentation system for GOV.UK PaaS published at [docs.cloud.service.gov.uk](https://docs.cloud.service.gov.uk).\n\nDocumentation for the technical documentation tool is published at [https://tdt-documentation.london.cloudapps.digital](https://tdt-documentation.london.cloudapps.digital) [external link].\n\n## Getting started\n\nClone this repository to a folder on your computer.\n\nInstall Ruby with Rubygems, preferably with [Ruby version manager](https://rvm.io/),\nand the [Bundler gem](https://bundler.io/).\n\nIn the application folder, type the following to install the required gems:\n\n```\nbundle install\n```\n\n## Making changes\n\nTo make changes, edit the markdown files in the `source` folder.\n\nAlthough a single page of HTML is generated, the markdown is spread across\nmultiple files to make it easier to manage. They can be found in\n`source/documentation`.\n\nA new markdown file is not automatically included in the generated output. If you\nadd a new markdown file at the location `source/documentation/agile/scrum.md`,\nthe following snippet in `source/index.html.md.erb` will include it in the\ngenerated output.\n\n```\n\u003c%= partial 'documentation/agile/scrum' %\u003e\n```\n\nIncluding files manually like this enables you to specify the position they appear in\nthe page.\n\nThe sections in the documentation are controlled by the use of markdown headers, *not* the file structure.\n\nImages to be included in the docs are kept in `source/documentation/figures`\n\nIn order to configure some aspects of layout, like the header, edit ``config/tech-docs.yml``.\n\n## Preview\n\nWhilst writing documentation, you can run a middleman server to preview how the\npublished version will look in the browser.\n\nThe preview is only available on your own computer. Others will not be able to\naccess it if they are given the link.\n\nType the following to start the server:\n\n```\nbundle exec middleman server\n```\n\nIf all goes well something like the following output will be displayed:\n\n```\n== The Middleman is loading\n== LiveReload accepting connections from ws://192.168.0.8:35729\n== View your site at \"http://Laptop.local:4567\", \"http://192.168.0.8:4567\"\n== Inspect your site configuration at \"http://Laptop.local:4567/__middleman\", \"http://192.168.0.8:4567/__middleman\"\n```\n\nYou should now be able to view a live preview at [http://localhost:4567](http://localhost:4567).\n\nChanges to the `tech-docs.yml` file require stopping and restarting the server to show up in the preview. (Stop it with `Ctrl-C`).\n\n## Running tests\n\nThis repo is configured in GitHub actions to run a link-checker over the generated docs\nto find any broken links and so on. If you want to run this locally, do the\nfollowing:\n\n```\nvirtualenv .venv\nsource .venv/bin/activate\nmake dependencies\nmake test\n```\n\n## Build and deploy\n\nThe docs are hosted on GitHub Pages which is deployed using GitHub actions. GitHub pages is configured\nwith a custom sub-domain at [docs.cloud.service.gov.uk](https://docs.cloud.service.gov.uk).\n\nThe deploy process first runs `bundle exec middleman build` which generates a `build` directory consisting of static files for our site. \n\nNext the [upload-pages-artifact](https://github.com/actions/upload-pages-artifact) action takes the `build` directory and turns it into\n a [gzip archive](https://en.wikipedia.org/wiki/Gzip) called `github-pages` which the [deploy-pages](https://github.com/actions/deploy-pages) action uses to deploy to GitHub pages.\n\n## Updating the template\n\nThe master repository for the tech docs template system is at [https://github.com/alphagov/tech-docs-template](https://github.com/alphagov/tech-docs-template)\n\nThe template system is maintained and developed by the service design manual team.  You can contact them at `#tech-docs-format` on GDS Slack. Note that this is an MVP version and there is a roadmap of planned features and improvements.\n\n## Licence\n\nUnless stated otherwise, the codebase is released under [the MIT licence](https://opensource.org/license/mit/).\n\nThe data is [© Crown\ncopyright](http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/copyright-and-re-use/crown-copyright/)\nand available under the terms of the [Open Government\n3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/)\nlicence.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphagov%2Fpaas-tech-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falphagov%2Fpaas-tech-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphagov%2Fpaas-tech-docs/lists"}