govuk_tech_docs 6.2.4 → 6.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74dc4c44fa70d8f29bb050007da7bfc8740e690f3dda8b4220fc1cbf6246d08d
-  data.tar.gz: 972e4b78381b8a0d07384fd65dc8a40889b56458d31e3bfca60098a053e5b794
+  metadata.gz: e14e31166315775ce210071e6369ceed8e305111f6667a75e9dfb56216879616
+  data.tar.gz: 79b82c15e10ac592f12fa635db39838d0676cb86abcc2a33e654ed22cbe2cd7c
 SHA512:
-  metadata.gz: c9289ca8f68a4b0327d71355929f319dea91d1a8a72dcbb10a7190a51e6cf59f06ed5df79ed7acf3efa7989c180c29c43727931e64b8045741df4a6fa7b25495
-  data.tar.gz: 7e02307c317a55e7075c71d537fa0e11c60c7250af9c6851f2e45e6068cb8f8fde3236f9202811049e557047c078a5bd9a48e324ff6f19ae57ae651b4f556dae
+  metadata.gz: 8fea921277de197457d49755c9c7ddee7cf60cfcff80e599304824a47b6f094e58947a7673f849719b00a730a7d2a6b4c9e5933b5c70b5d0d9b627d797c30cf2
+  data.tar.gz: 2009a67d569ae66cfeda08739e7223a74da595bdba126a9bb0f440bb5c5704ec90e8285ea543a4943ea794350b7fdffafb0e230f2aa308d8c71d9db1ed24fc3b

data/.github/ISSUE_TEMPLATE/documentation.yaml

@@ -0,0 +1,29 @@
+name: ✨ New or updated documentation
+description: Suggest a new feature or improvement
+title: "[Documentation]: "
+labels: ["documentation"]
+body:
+  - type: checkboxes
+    id: documentation-type
+    attributes:
+      label: Is this
+      options:
+        - label: a suggestion for new content
+          required: false
+        - label: an update to existing content
+          required: false
+        - label: a suggestion to remove content
+          required: false
+
+  - type: textarea
+    id: user-need
+    attributes:
+      label: User need
+      description: Do you have evidence that the change will meet the needs of users? Let us know about any user research or testing you’ve done
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Optional — describe how you think this would look or link to a draft
+

data/.github/workflows/build-middleman-artifact.yaml

@@ -0,0 +1,41 @@
+name: 'Build middleman artifact'
+on:
+  workflow_call:
+    inputs:
+      upload-artifact:
+        default: false
+        required: false
+        type: boolean
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: documentation
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: 'documentation/.nvmrc'
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@89f90524b88a01fe6e0b732220432cc6142926af # v1.313.0
+        with:
+          bundler-cache: true
+          working-directory: documentation
+          ruby-version: '3'
+      - name: Install gems
+        run: bundle install
+      - name: Build
+        run: bundle exec middleman build
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v4.1.3
+        if: ${{ inputs.upload-artifact }}
+        with:
+          name: build
+          path: documentation/build/**
+          retention-days: 1

data/.github/workflows/dependency-review.yaml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: 'Checkout Repository'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: 'Dependency Review'
         uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 #5.0.0
         with:

data/.github/workflows/deploy-to-pages.yaml

@@ -0,0 +1,39 @@
+name: 'Deploy to GitHub Pages'
+on:
+  push:
+    branches: ["main", "feature/publish-documentation"]
+    paths: ['documentation/**']
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    uses: ./.github/workflows/build-middleman-artifact.yaml
+    with:
+      upload-artifact: true
+  deploy-to-pages:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c #v8.0.1
+        with:
+          name: build
+          path: build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 #v5.0.0
+        with:
+          path: "build"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

data/.github/workflows/publish.yaml

@@ -16,11 +16,11 @@ jobs:
       go: ${{ steps.gem_version.outputs.new_version }}
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           show-progress: false
 
-      - uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+      - uses: ruby/setup-ruby@89f90524b88a01fe6e0b732220432cc6142926af # v1.313.0
         with:
           ruby-version: '3'
 
@@ -48,7 +48,7 @@ jobs:
     if: needs.pre.outputs.go == 'true'
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           show-progress: false
 
@@ -57,7 +57,7 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'npm'
 
-      - uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+      - uses: ruby/setup-ruby@89f90524b88a01fe6e0b732220432cc6142926af # v1.313.0
         with:
           ruby-version: '3'
           bundler-cache: true

data/.github/workflows/test.yaml

@@ -22,7 +22,7 @@ jobs:
         ruby: ['3.3', '3.4', '4.0']
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           show-progress: false
 
@@ -31,10 +31,16 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'npm'
 
-      - uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+      - uses: ruby/setup-ruby@89f90524b88a01fe6e0b732220432cc6142926af # v1.313.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
-      - name: Run tests
-        run: bundle exec rake
+      - name: Lint Ruby and javascript files
+        run: bundle exec rake lint
+
+      - name: Run Ruby unit tests
+        run: bundle exec rake spec
+
+      - name: Run Javascript tests
+        run: bundle exec rake jasmine:ci

data/.gitignore

@@ -10,7 +10,7 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
-
+.idea/
 # Used by dotenv library to load environment variables.
 # .env
 
@@ -28,9 +28,10 @@
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
 
-/example/build
-/example/.bundle
-/example/.sass-cache
+/spec/test-site/build
+/spec/test-site/.bundle
+/spec/test-site/.sass-cache
 
 Gemfile.lock
 node_modules
+documentation/build/

data/.rubocop.yml

@@ -3,7 +3,7 @@ inherit_gem:
     - config/default.yml
 
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.3.0
 
 Layout/HeredocIndentation:
   Enabled: false
@@ -13,3 +13,7 @@ Naming/HeredocDelimiterNaming:
 
 Lint/NestedMethodDefinition:
   Enabled: false
+
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/tasks/**/*'

data/.vale.ini

@@ -0,0 +1,10 @@
+StylesPath = styles
+Packages = https://github.com/alphagov/tech-docs-linter/releases/latest/download/tech-writing-style-guide.zip
+SkippedScopes = pre, code, script, style
+MinAlertLevel = suggestion
+[*.{md,org,txt,erb,html}]
+
+BasedOnStyles = tech-writing-style-guide
+TokenIgnores = `[^`]+`
+
+; full docs about vale.ini options are at https://vale.sh/docs/vale-ini

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 6.3.0
+
+- Bugfix [issue 258](https://github.com/alphagov/tech-docs-template/issues/258) - page layout structure to remove whitespace on short pages ([pull request 513](https://github.com/alphagov/tech-docs-gem/pull/513))  
+- [6.3.0.beta](#630beta) 
+
+## 6.3.0.beta
+
+- Add `exe/tech_docs_jobs` to allow executable `Rake` commands
+- Add `rake task` for style guide linting
+- Add `lib/tasks/helpers/linter_report.rb` and `lib/tasks/helpers/vale_report.rb` for formatting output
+- Add `.vale.ini` to include [`tech-docs-linter`](https://github.com/alphagov/tech-docs-linter/tree/main#rules) rules
+- Update `README.md`
+
 ## 6.2.4
 
 - Support non-JSON response content types in OpenAPI renderer.
@@ -219,7 +232,7 @@ You can see more detail about this issue at [#323: Fix XSS vulnerability on sear
 
 There are some steps you should follow as the Technical Documentation Template (TDT) now uses GOV.UK Frontend 4.4.1.
 
-1. Update your documentation site to use the latest template version. You can [follow the TDT guidance on using the latest template version](https://tdt-documentation.london.cloudapps.digital/maintain_project/use_latest_template/).
+1. Update your documentation site to use the latest template version. You can [follow the TDT guidance on using the latest template version](https://alphagov.github.io/tech-docs-gem/maintain_project/use_latest_template/).
 2. Check your documentation site displays correctly. If your site does not display correctly, you can refer to the [GOV.UK Frontend release notes](https://github.com/alphagov/govuk-frontend/releases/) for more information, or [contact the GOV.UK Design System team](https://design-system.service.gov.uk/get-in-touch/).
 
 ### Fixes
@@ -236,7 +249,7 @@ There are some steps you should follow as the Technical Documentation Template (
 
 ### New features
 
-You can now [configure your Tech Docs Template (TDT) to build your documentation site to use relative links to pages and assets](https://tdt-documentation.london.cloudapps.digital/configure_project/global_configuration/#build-your-site-using-relative-links).
+You can now [configure your Tech Docs Template (TDT) to build your documentation site to use relative links to pages and assets](https://alphagov.github.io/tech-docs-gem/configure_project/global_configuration/#build-your-site-using-relative-links).
 
 Thanks [@eddgrant](https://github.com/eddgrant) for contributing this feature and the associated fixes.
 
@@ -248,7 +261,7 @@ This change was introduced in [pull request #291: Support sites deployed on path
 
 There are some steps you should follow as the Technical Documentation Template (TDT) now uses GOV.UK Frontend 4.0.0.
 
-1. Update your documentation site to use the latest template version. You can [follow the TDT guidance on using the latest template version](https://tdt-documentation.london.cloudapps.digital/maintain_project/use_latest_template/).
+1. Update your documentation site to use the latest template version. You can [follow the TDT guidance on using the latest template version](https://alphagov.github.io/tech-docs-gem/maintain_project/use_latest_template/).
 2. Check your documentation site displays correctly. If your site does not display correctly, you can refer to the [GOV.UK Frontend 4.0.0 release note](https://github.com/alphagov/govuk-frontend/releases/tag/v4.0.0) for more information.
 
 ## 3.0.1
@@ -457,7 +470,7 @@ Fixes bug where search results disappear when opening results in a new tab, maki
 
 Adds a `show_expiry` config option to allow you to choose whether to show the review due date and expired banner from your pages. Find out more about the [page expiry and review feature][expiry].
 
-[expiry]: https://tdt-documentation.london.cloudapps.digital/page-expiry.html#page-expiry-and-review
+[expiry]: https://alphagov.github.io/tech-docs-gem/page-expiry.html#page-expiry-and-review
 
 ## 1.8.1
 

data/README.md

@@ -1,27 +1,66 @@
 # Tech Docs Template - gem
 
-This repo contains the Ruby gem that distributes the [Tech Docs Template][tdt-template]. The Tech Docs Template is a [middleman template][mmt] that
+This repo contains the Ruby gem that distributes the [Tech Docs Template][tdt-template]. The Tech Docs Template is
+a [middleman template][mmt] that
 you can use to build technical documentation using a GOV.UK style.
 
-To find out more about setting up and managing content for a website using this template, see the [Tech Docs Template documentation][tdt-docs].
+To find out more about setting up and managing content for a website using this template, see
+the [Tech Docs Template documentation][tdt-docs].
 
 ## Contributing
 
 Everybody who uses this project is encouraged to contribute.
 
-Find out how to [contribute](https://tdt-documentation.london.cloudapps.digital/support/#contribute).
+Find out how to [contribute](https://alphagov.github.io/tech-docs-gem/support/#contribute).
+
+## Rake tasks
+
+This gem contains `Rake` tasks that you can use to run the linter against your middleman build. To list the available
+jobs you can run the command:
+
+```shell
+bundle exec tech_docs_jobs -T
+```
+
+### Tech-docs-linter
+
+The `tech-docs-linter` is a set of `Vale` linting rules which can help you check your content meets the gov.uk style
+guide. To find out more about the linter visit the [GitHub repository](https://github.com/alphagov/tech-docs-linter).
+`Vale` is designed to evaluate written content, and does not recommend auto-fixing. You should review the output report
+and manually resolve alerts where appropriate.
+
+The `vale:lint` task returns a 0 exit code unless there is an `Exception`.  This allows you to run the linter without interrupting your `CI/CD workflows`.
+
+You can run the linting task from your project root with the command:
+
+```shell
+bundle exec tech_docs_jobs lint:vale
+```
+
+The linting job can take the following optional parameters:
+
+| Name          | Definition                                                                                  | Default   |
+|---------------|---------------------------------------------------------------------------------------------|-----------|
+| `target`      | Directory of your middleman build, relative to the root of your project.                    | './build' |
+| `clean_build` | If true runs `bundle exec middleman build` to create a clean build.                         | 'true'    |
+| `full_output` | If true the full report is printed to the console, otherwise only the summary is displayed. | 'true'    |
 
 ## GOV.UK frontend
 
-This gem uses [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), part of the [GOV.UK Design System](https://design-system.service.gov.uk/).
+This gem uses [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), part of
+the [GOV.UK Design System](https://design-system.service.gov.uk/).
 
-This gem can also use [GOV.UK Design System nunjucks components](https://design-system.service.gov.uk/components/).  It is recommended that you use these as they are user researched and accessibility tested.  An example using the `govukButton` component is available in the [example site in this gem](./example/source/index.html.md.erb).
+This gem can also use [GOV.UK Design System nunjucks components](https://design-system.service.gov.uk/components/). It
+is recommended that you use these as they are user researched and accessibility tested. An example using the
+`govukButton` component is available in the [example site in this gem](spec/example/source/index.html.md.erb).
 
-We use `npm` to download the govuk-frontend package. To update to a new version, change the version in the [package.json file](package.json) and run `npm update`.
+We use `npm` to download the govuk-frontend package. To update to a new version, change the version in
+the [package.json file](package.json) and run `npm update`.
 
 ## Table of contents helper functions
 
-With `Middleman` you can apply layouts to group pages and customise sites. This gem has the following additional helper functions to manage the table of contents (ToC):
+With `Middleman` you can apply layouts to group pages and customise sites. This gem has the following additional helper
+functions to manage the table of contents (ToC):
 
 - `single_page_table_of_contents` to create a ToC from the headings on the current page
 - `multi_page_table_of_contents` to create a ToC for a group of pages, opened at the current page
@@ -48,7 +87,7 @@ end
 %>
 ```
 
-This example will create a ToC containing the current page title, and nested headings to a depth of 2. 
+This example will create a ToC containing the current page title, and nested headings to a depth of 2.
 
 ### Multi page table of contents
 
@@ -73,14 +112,17 @@ wrap_layout :core do
 end
 %>
 ```
-This example will create a ToC containing the page title of each resource, as a heading.  Each heading can be expanded to show nested headings to the depth defined in the site config.  If `include_child_resources` is set to `true`, child resources will also be included.
+
+This example will create a ToC containing the page title of each resource, as a heading. Each heading can be expanded to
+show nested headings to the depth defined in the site config. If `include_child_resources` is set to `true`, child
+resources will also be included.
 
 ## Developing locally
 
 There are 2 ways to develop with this gem. You can see your changes on either:
 
 - your own Tech Docs Template website
-- the example in this repository
+- the documentation in this repository
 
 ### Use your own Tech Docs Template website
 
@@ -90,36 +132,63 @@ To see how your changes to the gem affect your website, point your website's Gem
 gem 'govuk_tech_docs', path: '../tech-docs-gem'
 ```
 
-To preview your documentation changes locally, see the [Tech Docs Template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
+To preview your documentation changes locally, see
+the [Tech Docs Template documentation on previewing your documentation](https://alphagov.github.io/tech-docs-gem/create_project/preview/#preview-your-documentation).
 
-If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave).
+If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should
+refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave).
 
-### Use the example in this repo
+### Use the documentation in this repo
 
-To start the example in this repo, run:
+To start the documentation in this repo, run:
 
 ```sh
-cd example
+cd documentation
 bundle install
 bundle exec middleman server
 ```
 
 See your website on `http://localhost:4567` in your browser.
 
-If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave).
+If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should
+refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave).
 
-For more information on previewing your documentation locally, see the [Tech Docs template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
+For more information on previewing your documentation locally, see
+the [Tech Docs template documentation on previewing your documentation](https://alphagov.github.io/tech-docs-gem/create_project/preview/#preview-your-documentation).
 
 ## Tests
 
-Use this command to run the linting and tests for the Ruby and JavaScript code:
+### Ruby tests and linting
+
+You can run the Ruby test suite with the following command:
+
+```shell
+bundle exec rspec
+```
+
+To test a specific file include the filepath after `rspec`.
+
+You can lint the ruby code with the command:
+
+```shell
+bundle exec rubocop
+```
+
+Rubocop can automatically fix some linting issues. If the above command has suggestions that you automatically fix them
+with:
+
+```shell
+bundle exec rubocop -a 
+```
+
+### JavaScript tests and linting
+
+Use this command to run the linting and tests for the JavaScript code:
 
 ```sh
 bundle exec rake
 ```
 
-### JavaScript tests
-
 The JavaScript tests use the [Jasmine test framework][jas].
 
 You can run these tests on their own and see the results in your browser.
@@ -140,28 +209,38 @@ Users on OSX Mojave (10.14) may get this error when running `bundle exec middlem
 There are 3 possible ways to solve this. From best to worst, you can:
 
 * upgrade to macOS 10.15 (Catalina) or higher
-* tell rubygems not to use the system ffi by running `gem install ffi -- --disable-system-libffi` in the command line when the error shows
+* tell rubygems not to use the system ffi by running `gem install ffi -- --disable-system-libffi` in the command line
+when the error shows
 * pin the ffi version back to 1.12.2 by editing the Gemfile of your app
 
 ## Releasing new versions
 
-To release a new version, create a new pull request (PR) that updates [version.rb](lib/govuk_tech_docs/version.rb) and [CHANGELOG.md](CHANGELOG.md).
+To release a new version, create a new pull request (PR) that updates [version.rb](lib/govuk_tech_docs/version.rb)
+and [CHANGELOG.md](CHANGELOG.md).
 
-Do not include other changes in your pull request, as this makes it easier to find out what was released when. See an example of a [PR for releasing a new version](https://github.com/alphagov/tech-docs-gem/pull/15).
+Do not include other changes in your pull request, as this makes it easier to find out what was released when. See an
+example of a [PR for releasing a new version](https://github.com/alphagov/tech-docs-gem/pull/15).
 
 Travis will automatically release a [new version to Rubygems.org](https://rubygems.org/gems/govuk_tech_docs).
 
 ## Licence
 
-Unless stated otherwise, the codebase is released under [the MIT License][mit]. This covers both the codebase and any sample code in the documentation.
+Unless stated otherwise, the codebase is released under [the MIT License][mit]. This covers both the codebase and any
+sample code in the documentation.
 
-The documentation is [© Crown copyright][copyright] and available under the terms of the [Open Government 3.0][ogl] licence.
+The documentation is [© Crown copyright][copyright] and available under the terms of the [Open Government 3.0][ogl]
+licence.
 
 [mit]: LICENCE
+
 [copyright]: http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/
+
 [ogl]: http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
-[tdt-docs]: https://github.com/alphagov/tdt-documentation/
+
+[tdt-docs]: https://alphagov.github.io/tech-docs-gem/
+
 [tdt-template]: https://github.com/alphagov/tech-docs-template
+
 [mmt]: https://middlemanapp.com/advanced/project_templates/
 
 [jas]: https://jasmine.github.io/

data/Rakefile

@@ -16,7 +16,7 @@ end
 
 desc "Lint Ruby and JavaScript"
 task :lint do
-  sh "rubocop example lib spec Rakefile"
+  sh "rubocop -a spec/test-site documentation lib spec Rakefile"
   sh "npm run lint --silent"
 end
 

data/documentation/.nvmrc

@@ -0,0 +1 @@
+20

data/documentation/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+# For faster file watcher updates on Windows:
+gem "wdm", "~> 0.1.0", platforms: %i[mswin mingw]
+
+# Windows does not come with time zone data
+gem "tzinfo-data", platforms: %i[mswin mingw jruby]
+
+gem "govuk_tech_docs", path: ".."
+
+gem "middleman-gh-pages"

data/documentation/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Crown Copyright (Government Digital Service)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/documentation/README.md

@@ -0,0 +1,30 @@
+# Tech Docs Template Documentation
+
+This directory contains the documentation for the [`tech-docs-template`](https://github.com/alphagov/tech-docs-template), which uses the gem in this repository.
+
+The documentation covers:
+
+- creating and updating a site with the tech docs template
+- examples of how to use the gem helpers
+
+To start the documentation in this repo, run:
+
+```sh
+cd documentation
+bundle install
+bundle exec middleman server
+```
+
+## Publishing changes
+
+GitHub Actions automatically publishes changes merged into the main branch of this repository to [https://alphagov.github.io/tech-docs-gem/](https://alphagov.github.io/tech-docs-gem/).
+
+## Code of conduct
+
+Refer to the `alphagov` [code of conduct](https://github.com/alphagov/code-of-conduct).
+
+## Licence
+
+Unless stated otherwise, the codebase is released under the [MIT License](LICENSE). This covers both the codebase and any sample code in the documentation.
+
+The documentation is [© Crown copyright](http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/copyright-and-re-use/crown-copyright/) and available under the terms of the [Open Government 3.0 licence](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

data/documentation/Staticfile

@@ -0,0 +1,4 @@
+root: build 
+http_strict_transport_security: true
+http_strict_transport_security_include_subdomains: true
+location_include: includes/*.conf

data/documentation/config/tech-docs.yml

@@ -0,0 +1,45 @@
+# Host to use for canonical URL generation (without trailing slash)
+host: https://alphagov.github.io/tech-docs-gem
+
+# Header-related options
+show_govuk_logo: false
+service_name: Tech docs template
+service_link: https://alphagov.github.io/tech-docs-gem
+phase: Beta
+
+# Uncomment if you do not want to activate the GOV.UK Design System component extension
+enable_govuk_components: true
+
+# Links to show on right-hand-side of header
+header_links:
+  Template: https://github.com/alphagov/tech-docs-template
+  Ruby gem: https://github.com/alphagov/tech-docs-gem
+  Support: /support
+footer_links:
+  Accessibility: /accessibility/
+  
+# Table of contents depth – how many levels to include in the table of contents.
+# If your ToC is too long, reduce this number and we'll only show higher-level
+# headings.
+max_toc_heading_level: 1
+
+# Multi-page options
+multipage_nav: true
+collapsible_nav: true
+
+# Show links to contribute on GitHub
+show_contribution_banner: true
+github_repo: https://github.com/alphagov/tech-docs-gem/documentation
+
+# Enable search
+enable_search: true
+
+# Ownership for page reviews
+default_owner_slack: '#gds-technical-writing'
+owner_slack_workspace: gds
+
+redirects:
+  page-expiry.html: configure_project/page_expiry_and_review/#set-review-date-for-pages
+  search.html: configure_project/global_configuration/#enable-search
+  content.html: write_docs/content/#write-your-content
+  create_new_project.html: create_project/create_new_project/#create-a-new-documentation-project