Add guide for upgrading from v5 to v6

x-govuk · Dec 23, 2023 · d3ffb15 · d3ffb15
1 parent e666e62
commit d3ffb15
Show file tree

Hide file tree

Showing 4 changed files with 159 additions and 93 deletions.
diff --git a/docs/upgrading.md b/docs/upgrading.md
@@ -1,100 +1,12 @@
 ---
 layout: sub-navigation
 order: 10
-title: Upgrading from v2 to v3
-description: v3.0.0 contains a number of breaking changes.
+title: Upgrading
+description: Guides for upgrading to major releases with breaking changes
 ---
 
-## Side navigation layout
+{% for page in collections.upgrading %}
 
-The `side-navigation` layout has been renamed `sub-navigation`, so use this new name wherever you call this layout. For example, in a document’s front matter:
+- [{{ page.data.title }}]({{ page.url | url }})
 
-```diff
-- layout: side-navigation
-+ layout: sub-navigation
-  title: My post
-```
-
-## Open Graph images
-
-Plugin and front matter option names have been updated to match names [introduced in `govuk-frontend` v4.3.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.3.0).
-
-### Setting a default Open Graph image
-
-Within plugin options, `ogImage` has been renamed `opengraphImageUrl`. A complete URL is also now required for this value.
-
-Example:
-
-```diff
-  eleventyConfig.addPlugin(govukEleventyPlugin, {
--   ogImage: '/assets/opengraph-image.png',
-+   opengraphImageUrl: 'https://example.org/assets/opengraph-image.png',
-  })
-```
-
-### Using a post image as Open Graph image
-
-Within front matter options, `image.ogImage` has been renamed `image.opengraphImage`. For example:
-
-```diff
-  image:
-    src: "/assets/post-image.png"
-    alt: "Post image"
--   ogImage: true
-+   opengraphImage: true
-```
-
-### Adding an Open Graph image to a document
-
-Within front matter options, `ogImage` has been renamed `opengraphImage`. For example:
-
-```diff
-- ogImage:
-+ opengraphImage:
-    src: "/assets/another-opengraph-image.png"
-    alt: "Another Open Graph image"
-```
-
-## Footer options
-
-Plugin options have been updated to better align with the changes to the footer component [introduced in `govuk-frontend` v4.3.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.3.0).
-
-### Setting a custom content licence
-
-You can now change the content licence in the footer using the `footer.contentLicence` option. This replaces `footer.licence`.
-
-`footer.contentLicence` takes either a `text` or `html` value, and no longer parses Markdown. Unlike the component in the Design System, using this option will prevent the OGL logo from appearing to the left of the content licence.
-
-Example:
-
-```diff
-  eleventyConfig.addPlugin(govukEleventyPlugin, {
-    footer: {
--     licence: 'Licensed under the MIT Licence'
-+     contentLicence: {
-+       text: 'Licensed under the MIT Licence'
-+     }
-    }
-  })
-```
-
-### Setting a custom copyright statement
-
-`footer.copyright` takes either a `text` or `html` value, and no longer parses Markdown. Unlike the component in the Design System, using this option prevents the Royal Coat of Arms from appearing above the copyright statement.
-
-Example:
-
-```diff
-  eleventyConfig.addPlugin(govukEleventyPlugin, {
-    footer: {
--     copyright: '© 2022 My Organistion'
-+     copyright: {
-+       text: '© 2022 My Organistion'
-+     }
-    }
-  })
-```
-
-## Article component
-
-If you were [overriding a layout](https://x-govuk.github.io/govuk-eleventy-plugin/layouts/#overriding-layouts) and using the `appArticle` component, this has been removed and replaced with separate `appDocumentHeader` and `appDocumentFooter` components.
+{% endfor %}
diff --git a/docs/upgrading/2-to-3.md b/docs/upgrading/2-to-3.md
@@ -0,0 +1,102 @@
+---
+layout: sub-navigation
+order: 2
+title: Upgrading from v2 to v3
+description: v3.0.0 contained a number of breaking changes.
+eleventyNavigation:
+  parent: Upgrading
+---
+
+## Side navigation layout
+
+The `side-navigation` layout was renamed `sub-navigation`, so use this name wherever you call this layout. For example, in a document’s front matter:
+
+```diff
+- layout: side-navigation
++ layout: sub-navigation
+  title: My post
+```
+
+## Open Graph images
+
+Plugin and front matter option names were updated to match names [introduced in `govuk-frontend` v4.3.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.3.0).
+
+### Setting a default Open Graph image
+
+Within plugin options, `ogImage` was renamed to `opengraphImageUrl`. A complete URL is also required for this value.
+
+Example:
+
+```diff
+  eleventyConfig.addPlugin(govukEleventyPlugin, {
+-   ogImage: '/assets/opengraph-image.png',
++   opengraphImageUrl: 'https://example.org/assets/opengraph-image.png',
+  })
+```
+
+### Using a post image as Open Graph image
+
+Within front matter options, `image.ogImage` was renamed `image.opengraphImage`. For example:
+
+```diff
+  image:
+    src: "/assets/post-image.png"
+    alt: "Post image"
+-   ogImage: true
++   opengraphImage: true
+```
+
+### Adding an Open Graph image to a document
+
+Within front matter options, `ogImage` was renamed `opengraphImage`. For example:
+
+```diff
+- ogImage:
++ opengraphImage:
+    src: "/assets/another-opengraph-image.png"
+    alt: "Another Open Graph image"
+```
+
+## Footer options
+
+Plugin options were updated to better align with the changes to the footer component [introduced in `govuk-frontend` v4.3.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.3.0).
+
+### Setting a custom content licence
+
+You can change the content licence in the footer using the `footer.contentLicence` option. This replaces `footer.licence`.
+
+`footer.contentLicence` takes either a `text` or `html` value, and no longer parses Markdown. Unlike the component in the Design System, using this option will prevent the OGL logo from appearing to the left of the content licence.
+
+Example:
+
+```diff
+  eleventyConfig.addPlugin(govukEleventyPlugin, {
+    footer: {
+-     licence: 'Licensed under the MIT Licence'
++     contentLicence: {
++       text: 'Licensed under the MIT Licence'
++     }
+    }
+  })
+```
+
+### Setting a custom copyright statement
+
+`footer.copyright` takes either a `text` or `html` value, and no longer parses Markdown. Unlike the component in the Design System, using this option prevents the Royal Coat of Arms from appearing above the copyright statement.
+
+Example:
+
+```diff
+  eleventyConfig.addPlugin(govukEleventyPlugin, {
+    footer: {
+-     copyright: '© 2022 My Organistion'
++     copyright: {
++       text: '© 2022 My Organistion'
++     }
+    }
+  })
+```
+
+## Article component
+
+If you were [overriding a layout](https://x-govuk.github.io/govuk-eleventy-plugin/layouts/#overriding-layouts) and using the `appArticle` component, this was removed and replaced with separate `appDocumentHeader` and `appDocumentFooter` components.
diff --git a/docs/upgrading/5-to-6.md b/docs/upgrading/5-to-6.md
@@ -0,0 +1,47 @@
+---
+layout: sub-navigation
+order: 1
+title: Upgrading from v5 to v6
+description: v6.0.0 contains a number of breaking changes.
+eleventyNavigation:
+  parent: Upgrading
+---
+
+## Customise GOV.UK Frontend settings
+
+It’s now possible to customise all [GOV.UK Frontend settings](https://frontend.design-system.service.gov.uk/sass-api-reference/#settings) to adjust the appearance of your site.
+
+Add values to a SCSS file and save it as `/sass/_settings.scss`, within your site’s [input directory](https://www.11ty.dev/docs/config/#input-directory). You can choose an alternative location for this settings file with the `scssSettingsPath` option.
+
+For example, to change your site’s brand colour and typeface, set values for the following SCSS variables:
+
+```scss
+$govuk-brand-colour: #2288aa;
+$govuk-font-family: system-ui, sans-serif;
+```
+
+With this more flexible method of customising styles available, the following options have been removed:
+
+- `brandColour` (`$govuk-brand-colour`)
+- `fontFamily` (`$govuk-font-family`)
+- `assetsPath` (`$govuk-assets-path`)
+- `fontsPath` (`$govuk-fonts-path`)
+- `imagesPath` (`$govuk-images-path`)
+
+## Customising the header
+
+With the introduction of [`govuk-frontend` version 5.0.0](https://github.com/alphagov/govuk-frontend/releases/tag/v5.0.0), the logo in the header is now provided as a single SVG image. To support this change, the following options have been added:
+
+- `header.logotype.text` - Text to show instead of the GOV.UK logo. This text will appear bold and replace the crown icon and ‘GOV.UK’ text.
+- `header.logotype.html` - HTML to use instead of the GOV.UK logo. Use this option to supply your own SVG image. If `header.logotype.text` is set, this is not required. If `header.logotype.html` is provided, the `header.logotype.text` option will be ignored.
+
+With this change, the following options have been removed:
+
+- `header.organisationLogo`
+- `header.organisationName`
+
+## `url` filter no longer required
+
+The plugin enables [Eleventy’s HTML base plugin](https://www.11ty.dev/docs/plugins/html-base/) which will rewrite URLs to include a configured `pathPrefix`.
+
+This means you no longer need to use the `url` filter. Remove this filter from any custom templates and check that any paths point to their correct location.
diff --git a/eleventy.config.js b/eleventy.config.js
@@ -66,6 +66,11 @@ module.exports = function (eleventyConfig) {
       ])
       .sort((a, b) => (a.data.order || 0) - (b.data.order || 0))
   )
+  eleventyConfig.addCollection('upgrading', (collection) =>
+    collection
+      .getFilteredByGlob(['docs/upgrading/*.md'])
+      .sort((a, b) => (a.data.order || 0) - (b.data.order || 0))
+  )
 
   // Passthrough
   eleventyConfig.addPassthroughCopy('./docs/assets')