Merge pull request #587 from alphagov/v5-section

Add a v5 version of the frontend docs

Author: owenatgov

.gitignore

@@ -25,4 +25,5 @@ Staticfile.auth
 
 # Sassdocs generated files
 data/sassdoc.json
+data/sassdoc-v5.json
 data/sassdoc-v4.json

config.rb

@@ -32,5 +32,6 @@ def markdown(content = nil)
   end
 end
 
+page "v5/*", layout: :v5, data: { parent: "/v5/" }
 page "v4/*", layout: :v4, data: { parent: "/v4/" }
 page "*", data: { parent: "/" }

config/tech-docs.yml

@@ -38,5 +38,6 @@ show_contribution_banner: true
 github_repo: alphagov/govuk-frontend-docs
 
 header_links:
-  v5.x (Latest): /
+  v6.x (Latest): /
+  v5.x: /v5/
   v4.x: /v4/

netlify.toml

@@ -30,3 +30,8 @@
   for = "/assets/govuk/assets/fonts/*"
   [headers.values]
     Cache-Control = "public,max-age=2147483648,immutable"
+
+[[redirects]]
+  from = "/changes-to-govuk-frontend-v5/"
+  to = "/v5/changes-to-govuk-frontend-v5/"
+  status = 301

package-lock.json

@@ -6,12 +6,15 @@
     "start": "bundle exec middleman server",
     "postinstall": "npm run build:sassdoc && npm run build:sassdocv4",
     "build:sassdoc": "sassdoc --no-update-notifier --parse node_modules/govuk-frontend/dist/govuk/ > data/sassdoc.json",
+    "build:sassdocv5": "sassdoc --no-update-notifier --parse node_modules/govuk-frontend-v5/dist/govuk/ > data/sassdoc-v5.json",
     "build:sassdocv4": "sassdoc --no-update-notifier --parse node_modules/govuk-frontend-v4/govuk/ > data/sassdoc-v4.json",
     "lint": "standard",
     "check-links": "hyperlink --canonicalroot https://frontend.design-system.service.gov.uk --internal --recursive build/index.html --skip 'property=\"og:image\"' | tee check-links.log | tap-mocha-reporter min"
   },
   "devDependencies": {
+
     "govuk-frontend": "^6.0.0-beta.2",
+    "govuk-frontend-v5": "npm:govuk-frontend@^5.14.0",
     "govuk-frontend-v4": "npm:govuk-frontend@^4.10.1",
     "hyperlink": "^5.0.4",
     "sassdoc": "^2.7.4",

package.json

@@ -7,36 +7,16 @@ weight: 4
 
 In June 2025, GOV.UK started to refresh the brand across its products and services.
 
-The changes affect these components:
+## If you’re using GOV.UK Frontend v6 or later
 
-- [GOV.UK header](https://design-system.service.gov.uk/components/header/)
-- [GOV.UK footer](https://design-system.service.gov.uk/components/footer/)
-- [Cookie banner](https://design-system.service.gov.uk/components/cookie-banner/)
-- [Service navigation](https://design-system.service.gov.uk/components/service-navigation/)
+You do not need to take any action. Your service is using the refreshed GOV.UK branding.
 
-## If you’re using GOV.UK Frontend v5
+## If you’re using GOV.UK Frontend v5 or earlier
 
-Update to the latest v5 release of GOV.UK Frontend. Follow the instructions in the [release notes for GOV.UK Frontend v5.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v5.10.0) to enable the new brand.
+We recommend upgrading to the latest version of GOV.UK Frontend as soon as possible to get the most up to date iteration of the GOV.UK brand.
 
-## If you’re using GOV.UK Frontend v4
+Read our [guidance on staying up to date with changes on GOV.UK Frontend](../staying-up-to-date/) for ways and benefits of knowing when we release new versions of GOV.UK Frontend.
 
-Update to the latest v4 release of GOV.UK Frontend. Follow the instructions in the [release notes for GOV.UK Frontend v4.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.10.0) to enable the new brand.
+### If you cannot upgrade or are not using GOV.UK Frontend
 
-## If you’re using GOV.UK Frontend v1, v2 or v3
-
-If you're either:
-
-- still migrating from GOV.UK Template, GOV.UK Frontend Toolkit or GOV.UK Elements
-- required to continue to fully support Internet Explorer 11 or other earlier browsers
-
-Update to the latest v4 release of GOV.UK Frontend. Follow the instructions in the [release notes for GOV.UK Frontend v4.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.10.0) to enable the new brand.
-
-Otherwise, update to the latest v5 release of GOV.UK Frontend, and then follow the instructions in the [release notes for GOV.UK Frontend v5.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v5.10.0) to enable the new brand.
-
-Follow the instructions in all the release notes from the version you are currently using, up to and including the version you are updating to. Pay particular attention to the release notes for any major releases.
-
-For help understanding which version you're currently using, and for more guidance on updating between major versions, see [staying up to date with changes](../staying-up-to-date/#how-the-version-numbering-works).
-
-## If you’re not using GOV.UK Frontend
-
-If you’ve not yet started migrating from GOV.UK Template, GOV.UK Frontend Toolkit and GOV.UK Elements, see our [guidance on migrating from our old frameworks](../v4/migrating-from-legacy-products/).
+Read the [GOV.UK Frontend v5 guidance on the brand refresh](/v5/brand-refresh-changes/).

source/brand-refresh-changes/index.html.md.erb

@@ -0,0 +1,26 @@
+<%
+wrap_layout :core do
+  html = yield
+
+  content_for(:toc_module, "in-page-navigation")
+
+  # For v5 pages, we only want the pages under the `v5` folder
+  resources = sitemap.resources.select do |r|
+    r.path.start_with?('v5/')
+  end
+
+  content_for :sidebar do
+    # Because all the pages for `v5` are children of `v5/index.html`,
+    # they'd appear as items under the v5 index in the sidebar, which we don't want
+    # so we exclude the rendering of child pages for the v5 index page
+    v5_index = resources.find{ |r| r.path == 'v5/index.html' }
+
+    with_page_in_navigation(v5_index) do
+      without_child_pages_for(v5_index) do
+        render_page_tree(resources, current_page, config, html)
+      end
+    end
+  end
+
+  html
+end %>

source/layouts/v5.erb

@@ -7,4 +7,4 @@ prevent_indexing: true
 
 # What upcoming changes to GOV.UK Frontend mean for your digital teams
 
-This page has been archived. See [Changes to GOV.UK Frontend v5.0.0](/changes-to-govuk-frontend-v5/) for more information.
+This page has been archived. See [Changes to GOV.UK Frontend v5.0.0](../v5/changes-to-govuk-frontend-v5/) for more information.

source/v5-0-announcement/index.html.md.erb

@@ -0,0 +1,42 @@
+---
+title: Updating your service to use the new brand
+weight: 4
+---
+
+# Updating your service to use the new brand
+
+In June 2025, GOV.UK started to refresh the brand across its products and services.
+
+The changes affect these components:
+
+- [GOV.UK header](https://design-system.service.gov.uk/components/header/)
+- [GOV.UK footer](https://design-system.service.gov.uk/components/footer/)
+- [Cookie banner](https://design-system.service.gov.uk/components/cookie-banner/)
+- [Service navigation](https://design-system.service.gov.uk/components/service-navigation/)
+
+## If you’re using GOV.UK Frontend v5
+
+Update to the latest v5 release of GOV.UK Frontend. Follow the instructions in the [release notes for GOV.UK Frontend v5.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v5.10.0) to enable the new brand.
+
+## If you’re using GOV.UK Frontend v4
+
+Update to the latest v4 release of GOV.UK Frontend. Follow the instructions in the [release notes for GOV.UK Frontend v4.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.10.0) to enable the new brand.
+
+## If you’re using GOV.UK Frontend v1, v2 or v3
+
+If you're either:
+
+- still migrating from GOV.UK Template, GOV.UK Frontend Toolkit or GOV.UK Elements
+- required to continue to fully support Internet Explorer 11 or other earlier browsers
+
+Update to the latest v4 release of GOV.UK Frontend. Follow the instructions in the [release notes for GOV.UK Frontend v4.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.10.0) to enable the new brand.
+
+Otherwise, update to the latest v5 release of GOV.UK Frontend, and then follow the instructions in the [release notes for GOV.UK Frontend v5.10.0](https://github.com/alphagov/govuk-frontend/releases/tag/v5.10.0) to enable the new brand.
+
+Follow the instructions in all the release notes from the version you are currently using, up to and including the version you are updating to. Pay particular attention to the release notes for any major releases.
+
+For help understanding which version you're currently using, and for more guidance on updating between major versions, see [staying up to date with changes](../staying-up-to-date/#how-the-version-numbering-works).
+
+## If you’re not using GOV.UK Frontend
+
+If you’ve not yet started migrating from GOV.UK Template, GOV.UK Frontend Toolkit and GOV.UK Elements, see our [guidance on migrating from our old frameworks](/v4/migrating-from-legacy-products/).