govuk_tech_docs 6.4.0.beta → 6.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bdc6cdd2fc1c883f3d0e5a3c25b3fce362207729376181436ce17d19ecf8bf0
-  data.tar.gz: 1eced113c1c927f274f513a2a84edfa5bc590e445845cf9b55af852d7ebe7fad
+  metadata.gz: 741a7042683c573724cdbab2c958d98306c55b0e81af89b9054952355a4a9268
+  data.tar.gz: a8a1cb466cdde9545ee2c8bdf46eb6c1e64d6a550f20073b6e9ad542d2aea189
 SHA512:
-  metadata.gz: bead1914b3ad00993bcf519a1931d70463e5a22c5f3c5665355ac39e24610b027ba54dc729f47142568af2ccfc5d3192c631e56adcedaa7c14f240a8eb3eb8f8
-  data.tar.gz: cabbdfc6bb527131c71a52be3bde21545967cb6afaa3797e35612c2fcf0a513268594d9cf0a773fa2dc735082d95390546c1374634745d850e7242765f30cd42
+  metadata.gz: 2c494c002dd3830aee443bb3caee5cbd345cb6fbc3f7439e3bf7aac0a1ee5270ff67673e1930038a498f9158245bd2de38332d8e4d05bdc4ed75ca64291e432c
+  data.tar.gz: ee4d71a1692537a142a57fc65b579fb44d65799114509ff8bfc7d1370c8a1849e2201043d06af45089df6ae60afc60223cc1b5022f77d4f9f7351e523153bb33

data/.github/dependabot.yml

@@ -1,8 +1,3 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-
 version: 2
 updates:
   # 1. Update Ruby dependencies (Gemfile/gemspec) in the root
@@ -12,9 +7,11 @@ updates:
       interval: "weekly"
       day: "monday"
       time: "06:00"
+    # Essential for gem projects without a Gemfile.lock:
+    versioning-strategy: "increase"
     commit-message:
       prefix: chore
-    open-pull-requests-limit: 3
+    open-pull-requests-limit: 5
     groups:
       prod-safe-updates:
         dependency-type: "production"
@@ -23,9 +20,15 @@ updates:
         update-types:
           - "minor"
           - "patch"
+      dev-safe-updates:
+        dependency-type: "development"
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
 
-
-  # 2. Update GitHub Actions (keeps your CI workflows secure)
+  # 2. Update GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
@@ -39,15 +42,15 @@ updates:
         patterns:
           - "*"
 
+  # 3. Update npm dependencies
   - package-ecosystem: "npm"
-    directory: "/" 
+    directory: "/"
     schedule:
       interval: "weekly"
       day: "monday"
       time: "06:00"
-    open-pull-requests-limit: 3
+    open-pull-requests-limit: 5
     groups:
-      # Group all "development" dependencies (linters, test runners, etc.)
       dev-dependencies:
         dependency-type: "development"
         patterns:
@@ -55,12 +58,10 @@ updates:
         update-types:
           - "patch"
           - "minor"
-      # Group all "production" dependencies (react, express, etc.) 
-      # but ONLY for minor/patch versions to avoid breaking changes
       prod-safe-updates:
         dependency-type: "production"
         patterns:
           - "*"
         update-types:
           - "patch"
-          - "minor"
+          - "minor"

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

@@ -23,7 +23,7 @@ jobs:
         with:
           node-version-file: 'documentation/.nvmrc'
       - name: Setup Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
         with:
           bundler-cache: true
           working-directory: documentation

data/.github/workflows/check-documentation-updates.yaml

@@ -17,15 +17,16 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           show-progress: false
+          fetch-depth: 2
 
-      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
         with:
           ruby-version: '3'
 
       - name: Documentation updated
         id: documentation_updated
         run: |
-          if git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep -q '^documentation/'; then
+          if git diff --name-only HEAD^ HEAD | grep -q '^documentation/'; then
             echo "documentation-updated=true" >> $GITHUB_OUTPUT
           else
             echo "documentation-updated=false" >> $GITHUB_OUTPUT

data/.github/workflows/check-gem-version.yaml

@@ -17,7 +17,7 @@ jobs:
         with:
           show-progress: false
 
-      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
         with:
           ruby-version: '3'
 

data/.github/workflows/npm-vulnerability-scanner.yaml

@@ -0,0 +1,55 @@
+name: NPM Audit Security Check
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  npm-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Run NPM Audit & Generate Summary
+        run: |
+          # 1. Run npm audit in JSON mode to capture raw audit metadata
+          AUDIT_JSON=$(npm audit --audit-level=high --json 2>/dev/null) || true
+
+          # 2. Extract counts using node's built-in JSON parser
+          CRITICAL_COUNT=$(echo "$AUDIT_JSON" | node -e "let d=''; process.stdin.on('data', c => d += c); process.stdin.on('end', () => { try { console.log(JSON.parse(d).metadata.vulnerabilities.critical || 0) } catch { console.log(0) } })")
+          HIGH_COUNT=$(echo "$AUDIT_JSON" | node -e "let d=''; process.stdin.on('data', c => d += c); process.stdin.on('end', () => { try { console.log(JSON.parse(d).metadata.vulnerabilities.high || 0) } catch { console.log(0) } })")
+          
+          # 3. Build GitHub Job Summary Markdown
+          echo "## 🛡️ NPM Dependency Audit Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          if [ "$CRITICAL_COUNT" -eq 0 ] && [ "$HIGH_COUNT" -eq 0 ]; then
+            echo "✅ **No high or critical vulnerabilities found!** All JS packages passed security checks." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "⚠️ **High/Critical Vulnerabilities Detected in npm Dependencies**" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "| Vulnerability Severity | Total Count |" >> $GITHUB_STEP_SUMMARY
+            echo "| :--- | :--- |" >> $GITHUB_STEP_SUMMARY
+            echo "| 🔴 **Critical** | $CRITICAL_COUNT \vert{}" >> $GITHUB_STEP_SUMMARY
+            echo "| 🟠 **High** | $HIGH_COUNT \vert{}" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### Detailed Audit Report" >> $GITHUB_STEP_SUMMARY
+            echo '```text' >> $GITHUB_STEP_SUMMARY
+            # Output human-readable audit text into the summary block
+            npm audit --audit-level=high 2>/dev/null || true
+            echo '```' >> $GITHUB_STEP_SUMMARY
+
+            # 4. Fail the workflow step
+            echo "::error::npm audit detected $CRITICAL_COUNT critical and $HIGH_COUNT high vulnerabilities."
+            exit 1
+          fi

data/.github/workflows/pipeline.yaml

@@ -6,13 +6,19 @@ on:
     branches: [ "main"]
 
 jobs:
-  dependency-review:
-    uses: ./.github/workflows/dependency-review.yaml
+  npm-vulnerability-scanner:
+    uses: ./.github/workflows/npm-vulnerability-scanner.yaml
+    permissions:
+      contents: read
+
+  ruby-vulnerability-scanner:
+    needs: npm-vulnerability-scanner
+    uses: ./.github/workflows/ruby-vulnerability-scanner.yaml
     permissions:
       contents: read
 
   test:
-    needs: dependency-review
+    needs: ruby-vulnerability-scanner
     uses: ./.github/workflows/test.yaml
     permissions:
       contents: read          # Allows the action to check out your repository code
@@ -42,7 +48,7 @@ jobs:
 
   publish-github-pages:
     needs: check-documentation-updates
-    if: github.event_name == 'push' && needs.check-documentation-updates.outputs.documentation-updated == 'true'
+    if: always() && github.event_name == 'push' && needs.check-documentation-updates.result == 'success' && needs.check-documentation-updates.outputs.documentation-updated == 'true'
     uses: ./.github/workflows/publish-github-pages.yaml
     permissions:
       contents: read

data/.github/workflows/publish-gem.yaml

@@ -35,7 +35,7 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'npm'
 
-      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
         with:
           ruby-version: '3'
           bundler-cache: true

data/.github/workflows/publish-github-pages.yaml

@@ -1,7 +1,7 @@
 name: Publish GitHub pages
 on:
   workflow_call:
-
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -35,4 +35,4 @@ jobs:
           path: "build"
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

data/.github/workflows/ruby-vulnerability-scanner.yaml

@@ -0,0 +1,44 @@
+name: Ruby vulnerability scanner
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  bundler-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Run Audit Check
+        run: |
+          gem install bundler-audit
+          
+          # Run audit and save output to file (preventing immediate job failure via || true)
+          bundle-audit check --update > audit_results.txt || AUDIT_EXIT_CODE=$?
+          
+          echo "## 🛡️ Ruby Dependency Audit Summary" >> $GITHUB_STEP_SUMMARY
+          
+          if [ -z "$AUDIT_EXIT_CODE" ]; then
+            echo "::notice::No vulnerabilities found in Ruby dependencies."
+            echo "✅ **No vulnerabilities found!** All resolved gems from your `.gemspec` passed security checks." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "⚠️ **Vulnerabilities Detected in Ruby Dependencies**" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo '```text' >> $GITHUB_STEP_SUMMARY
+            cat audit_results.txt >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+          
+            # Fail the step if vulnerabilities were found
+            exit $AUDIT_EXIT_CODE
+          fi

data/.github/workflows/test.yaml

@@ -2,6 +2,7 @@ name: Test
 
 on:
   workflow_call:
+  workflow_dispatch:
 
 permissions:
   contents: read          # Allows the action to check out your repository code
@@ -32,7 +33,7 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'npm'
 
-      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true

data/CHANGELOG.md

@@ -1,6 +1,35 @@
 ## Unreleased changes
 
-## 6.3.1.beta
+## 6.5.0
+
+### Changed
+
+- **potentially breaking**: `enable_govuk_components` has been removed from the config as these are now required for the header and footer.  If you are using this value for custom code or templates you should address this before updating.
+- added config settings:
+    - `product_name`
+    - `headerContainerClasses`
+    - `headerClasses`
+    - `navigationContainerClasses`
+    - `navigationClasses`
+
+[Check the documentation](https://design-system.service.gov.uk/components/header/) to see if you should add this value into your site.
+
+- updated header and footer layouts to use components
+
+### Deprecation warning
+
+- `show_govuk_logo:` setting will be removed in v7.x.x in to be replaced by the generic header and custom logo settings
+- `warning_text` custom extension will be removed in v7.x.x.  This was [marked as deprecated on 1st June 2026](https://github.com/alphagov/tech-docs-gem/commit/304230ba9c49759471a9a8f2daa425e37f846364#diff-2a7ef696e418f6044e5b18ae22c9cff4cac18481ae6fd0c1360ef978087b6cc9R8-R9).  You should now [use the GOV.UK warning text component](https://alphagov.github.io/tech-docs-gem/write_docs/content/#use-the-gov-uk-design-system).
+
+
+
+## 6.4.1
+
+- Bugfix: [Issue 283](https://github.com/alphagov/tech-docs-gem/issues/283) - correctly read report issue url (backwards compatible)
+- Update: [Issue 543](https://github.com/alphagov/tech-docs-gem/issues/543) - allow full git urls as well as just repository name for report issue url
+- [PR 542](https://github.com/alphagov/tech-docs-gem/pull/542) to improve vale linter handling and output when using rake task
+
+## 6.4.0.beta
 
 - [Remove govuk wrapper class](https://github.com/alphagov/tech-docs-gem/pull/530) that introduced extra padding 
 - Update[ template html syntax](https://github.com/alphagov/tech-docs-gem/pull/520) to more closely match gov.uk design template

data/README.md

@@ -45,6 +45,9 @@ The linting job can take the following optional parameters:
 | `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'    |
 
+
+If running the linter causes timeouts or crashes, you can use `bundle exec tech_docs_jobs lint:debug`.  You should use this locally, not as part of a pipeline.
+
 ## GOV.UK frontend
 
 This gem uses [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), part of
@@ -156,38 +159,26 @@ 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://alphagov.github.io/tech-docs-gem/create_project/preview/#preview-your-documentation).
 
-## Tests
 
-### Ruby tests and linting
-
-You can run the Ruby test suite with the following command:
+## Linting
 
-```shell
-bundle exec rake spec
-```
+You should run the linter before pushing any changes to GitHub to check for errors and correct formatting.  You can run linter jobs for ruby by running `bundle exec rubocop`. If you would like the linter to try and automatically fix any errors use `bundle exec rubocop -a`.  
 
-To test a specific file include the filepath after `rspec`.
+You can lint javascript files with the command `npm run lint`.  If only want to see the final result and not the full output, use `npm run lint --silent`.
 
-You can lint the ruby code with the command:
+You can also use the `Rakefile` job to run both together by running `bundle exec rake lint`.  See the [Rakefile](./Rakefile) for more detail.
 
-```shell
-bundle exec rubocop
-```
+### Ruby tests
 
-Rubocop can automatically fix some linting issues. If the above command has suggestions that you automatically fix them
-with:
+You can run the Ruby test suite with the following command:
 
 ```shell
-bundle exec rubocop -a 
+bundle exec rake spec
 ```
 
-### JavaScript tests and linting
+To test a specific file, use Rake's `SPEC` variable and set it to your filepath or directory.  For example `bundle exec rake spec SPEC=spec/govuk_tech_docs/meta_tags_spec.rb`
 
-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].
 

data/documentation/config/tech-docs.yml

@@ -3,14 +3,25 @@ host: https://alphagov.github.io/tech-docs-gem
 
 # Header-related options
 show_govuk_logo: false
+product_name:
 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
+#These can be used to add custom classes to the GOV.UK header, footer and service navigation components. You can find more detail about these on the component documentation at:
+#https://design-system.service.gov.uk/components/header/
+#https://design-system.service.gov.uk/components/service-navigation/
+#https://design-system.service.gov.uk/components/footer/
+
+headerContainerClasses:
+headerClasses:
+navigationContainerClasses:
+navigationClasses:
+footerContainerClasses:
+footerClasses:
+
+# Links to show on service navigation below header
 header_links:
   Template: https://github.com/alphagov/tech-docs-template
   Ruby gem: https://github.com/alphagov/tech-docs-gem
@@ -29,7 +40,7 @@ collapsible_nav: true
 
 # Show links to contribute on GitHub
 show_contribution_banner: true
-github_repo: https://github.com/alphagov/tech-docs-gem/documentation
+github_repo: https://github.com/alphagov/tech-docs-gem
 
 # Enable search
 enable_search: true

data/documentation/source/configure_project/global_configuration/index.html.md.erb

@@ -16,13 +16,23 @@ When you create your documentation project, the template creates a `tech-docs.ym
 host:
 
 # Header-related options
+product_name: GOV.UK Product
 show_govuk_logo: true
 service_name: My First Service
 service_link: https://www.larry-the-cat.service.gov.uk
 phase: Beta
 
-# Uncomment if you do not want to activate the GOV.UK Design System component extension 
-# enable_govuk_components: false
+#These can be used to add custom classes to the GOV.UK header, footer and service navigation components. You can find more detail about these on the component documentation at:
+#https://design-system.service.gov.uk/components/header/
+#https://design-system.service.gov.uk/components/service-navigation/
+#https://design-system.service.gov.uk/components/footer/
+
+headerContainerClasses:
+headerClasses:
+navigationContainerClasses:
+navigationClasses:
+footerContainerClasses:
+footerClasses:
 
 # Links to show on right-hand-side of header
 header_links:
@@ -56,7 +66,7 @@ github_repo: alphagov/YOUR_REPO
 github_branch: main
 ```
 
-<%= warning_text('All of these settings are optional. However, you should enable or disable settings to increase the usability of your documentation or because of best practice.') %>
+<%= govukWarningText({text: "All of these settings are optional. However, you should enable or disable settings to increase the usability of your documentation or because of best practice.", iconFallbackText: "Warning"}) %>
 
 You must wrap a value in quotes if it contains a colon, unless the value is a URL. For example:
 
@@ -88,6 +98,18 @@ Enables and disables the GOV.UK crown logo in the top left corner of the site. D
 show_govuk_logo: true
 ```
 
+<%= govukWarningText({text: "This setting is deprecated and will be replaced in version 7 by the generic header and custom logo options.", iconFallbackText: "Warning"}) %>
+
+### product_name
+
+Used for the `productName` value in the [GOV.UK header component](https://design-system.service.gov.uk/components/header/).  It is used when the product name follows on directly from ‘GOV.UK’. For example, GOV.UK Pay or GOV.UK Design System. In most circumstances, you should use the Service navigation component.
+
+```yaml
+product_name: "Great new product"
+```
+
+
+
 ### service_name
 
 Defines the service name in the header. Defaults to "My First Service" if you do not define it when creating your project.
@@ -112,7 +134,35 @@ Defines the phase of the service that the documentation is attached to. Defaults
 phase: "Beta"
 ```
 
-### enable_govuk_components
+### Header and footer custom styles
+
+If you have set `show_gouk_logo` to `true`, the header, service navigation and footer will use GOV.UK components.
+
+#### Container classes
+
+Classes for the container, useful if you want to make the header fixed width. The container settings you can configure are:
+
+- `headerContainerClasses:`
+- `navigationContainerClasses:`
+- `footerContainerClasses:`
+
+```yaml
+headerContainerClasses: "my-custom-container-style my-additional-styles"
+```
+
+You can add custom classes to the components in the same way.  The settings you can configure are:
+
+- `headerClasses:`
+- `navigationClasses:`
+- `footerClasses:`
+
+```yaml
+footerClasses: "my-custom-footer-style"
+```
+
+There is more detail on the [GOV.UK Design System](https://design-system.service.gov.uk/components) documentation site.
+
+### Govuk components
 
 The `tech-docs-gem` contains a custom extension to allow you to use [GOV.UK Design System components](https://design-system.service.gov.uk/components).  You can include these in your content by creating a `ruby` codeblock, and calling the component as described in the GOV.UK Design System documentation.  For example, you can include a [GOV.UK Button](https://design-system.service.gov.uk/components/button/):
 
@@ -123,7 +173,7 @@ The `tech-docs-gem` contains a custom extension to allow you to use [GOV.UK Desi
 This would be a short introduction, but now we need a button!
 
 
-<%%= govukButton({
+<%= govukButton({
   text: "Click me!"
 }) %>
 
@@ -211,12 +261,20 @@ show_contribution_banner: true
 
 ### github_repo
 
-Your documentation project's GitHub repository. You must enable this if you have enabled [show_contribution_banner].
+Your documentation project's GitHub repository. You must configure this if you have enabled [show_contribution_banner].
+
+Set this to either the repository's `owner/name` or its full GitHub URL. Link to the repository itself, rather than a file or directory, because the contribution banner builds its links relative to this URL.
 
 ```yaml
 github_repo: alphagov/example-repo
 ```
 
+You can also use the full URL:
+
+```yaml
+github_repo: https://github.com/alphagov/example-repo
+```
+
 ### github_branch
 
 Your project's GitHub default branch name. You can change this if your default branch is not named main.

data/documentation/source/maintain_project/use_latest_template/index.html.md.erb

@@ -23,8 +23,8 @@ Fetching gem metadata from https://rubygems.org/.............
 Fetching gem metadata from https://rubygems.org/.
 Resolving dependencies.......
 <...>
-Fetching govuk_tech_docs 2.0.11 (was 2.0.10)
-Installing govuk_tech_docs 2.0.11 (was 2.0.10)
+Fetching govuk_tech_docs 6.4.1.0 (was 6.2.0)
+Installing govuk_tech_docs 6.4.1.0 (was 6.2.0)
 <...>
 Bundle updated!
 ```

data/documentation/source/publish_project/deploy/index.html.md.erb

@@ -29,16 +29,16 @@ This method relies on adding a `Staticfile.auth` file to the `build` folder beca
 
 1. In the command line, navigate to your local documentation repo.
 
-1. If required, run `bundle exec middleman build` to create a `build` folder.
+2. If required, run `bundle exec middleman build` to create a `build` folder.
 
-1. Create a new `Staticfile.auth` file in the `build` folder.
+3. Create a new `Staticfile.auth` file in the `build` folder.
 
-1. Go to the [Htpasswd Generator].
+4. Go to the [Htpasswd Generator].
 
-1. Complete the __Username__ and __Password__ fields, and select __Create .htpasswd file__.
+5. Complete the __Username__ and __Password__ fields, and select __Create .htpasswd file__.
 
-1. Copy the generated username and password hash into the `Staticfile.auth` file and save.
+6. Copy the generated username and password hash into the `Staticfile.auth` file and save.
 
-1. Deploy your documentation site in line with your normal process.
+7. Deploy your documentation site in line with your normal process.
 
 <%= partial "partials/links" %>

data/documentation/source/write_docs/content/index.html.md.erb

@@ -110,6 +110,8 @@ You must include alt text for an image if the image has not been explained in su
 
 ## Insert a warning
 
+<%= govukWarningText({text: "This setting is deprecated and will be removed in version 7.  You should use the GOV.UK warning text component.", iconFallbackText: "Warning"}) %>
+
 Use the warning text component when you need to warn users about something important, such as legal consequences of an action, or lack of action, that they might take.
 
 This warning text format is consistent with the [GOV.UK Design System warning text][design-system].
@@ -117,12 +119,26 @@ This warning text format is consistent with the [GOV.UK Design System warning te
 To insert a warning, use the following:
 
 ```ruby
-<%%= warning_text('insert warning text here') %>
+<%= warning_text('insert warning text here') %>
 ```
 
+
 ## Use the GOV.UK Design System
 
-Use [GOV.UK Design System](https://design-system.service.gov.uk/) elements in your documentation to ensure your content complies with accessibility regulations.
+Use [GOV.UK Design System](https://design-system.service.gov.uk/) elements in your documentation to ensure your content complies with accessibility regulations.  To use a component from the design system call the component function inside a ruby block.  For example:
+
+```
+<%=
+govukPhaseBanner({
+  tag: {
+    text: "Alpha"
+  },
+  html: 'This is a new service. Help us improve it and <a class="govuk-link" href="#">give your feedback by email</a>.'
+})
+%>
+```
+
+You do not need to import the function using `from "govuk/components/{COMPONENT_NAME}/macro.njk" import {COMPONENT_NAME}`.  The extension will do this automatically.
 
 
 <%= partial "partials/links" %>

data/lib/assets/stylesheets/_govuk_tech_docs.scss

@@ -14,15 +14,7 @@ $govuk-new-link-styles: true;
 @import "govuk/core";
 @import "govuk/objects";
 
-@import "govuk/components/cookie-banner";
-@import "govuk/components/footer";
-@import "govuk/components/header";
-@import "govuk/components/service-navigation";
-@import "govuk/components/inset-text";
-@import "govuk/components/input";
-@import "govuk/components/tag";
-@import "govuk/components/skip-link";
-@import "govuk/components/warning-text";
+@import "govuk/components";
 
 @import "govuk/utilities";
 @import "govuk/overrides";

data/lib/assets/stylesheets/modules/_technical-documentation.scss

@@ -15,7 +15,10 @@
     @extend %govuk-heading-xl;
 
     &:first-of-type {
-      padding-top: govuk-spacing(6);
+      padding-top: govuk-spacing(4);
+      @include govuk-media-query(tablet) {
+        padding-top: govuk-spacing(8);
+      }
     }
   }