diff --git a/docs/upgrading.md b/docs/upgrading.md index a09373c1..e5ee026a 100644 --- 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 new file mode 100644 index 00000000..35c1b22e --- /dev/null +++ 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 new file mode 100644 index 00000000..a729d564 --- /dev/null +++ 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 index bca9641d..55d79048 100644 --- 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')