From 56fff3a03a85d87f88fa9815710f6c06d5d0c120 Mon Sep 17 00:00:00 2001 From: Paul Robert Lloyd Date: Mon, 22 Jul 2024 22:55:44 +0100 Subject: [PATCH] Add documentation on how to change the default design --- docs/design.md | 104 ++++++++++++++++++++++++++++++++++++++ docs/feed.md | 2 +- docs/hosting.md | 2 +- docs/layouts.md | 4 +- docs/markdown-advanced.md | 2 +- docs/markdown.md | 2 +- docs/options.md | 2 +- docs/search.md | 2 +- docs/tagging.md | 2 +- eleventy.config.js | 4 +- 10 files changed, 115 insertions(+), 11 deletions(-) create mode 100644 docs/design.md diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 00000000..f881109c --- /dev/null +++ b/docs/design.md @@ -0,0 +1,104 @@ +--- +layout: sub-navigation +order: 3 +title: Design +description: Replace the crown, GOV.UK logotype and GDS Transport typeface. +--- + +By default, the GOV.UK Eleventy Plugin generates pages that use the standard GOV.UK header and GDS Transport typeface. + +If your website isn’t considered part of GOV.UK, it must not: + +- identify itself as being part of GOV.UK +- use the crown or GOV.UK logotype in the header +- use the GDS Transport typeface +- suggest that it’s an official UK government website if it’s not + +It is strongly recommended that you change the default values to match your department or organisation’s own branding. + +## Replace the GOV.UK logotype and crown + +Use the `header.logotype.text` option to replace the crown and GOV.UK logotype with a text value. For example: + +```js +const govukEleventyPlugin = require('@x-govuk/govuk-eleventy-plugin') + +module.exports = function(eleventyConfig) { + eleventyConfig.addPlugin(govukEleventyPlugin, { + header: { + logotype: { + text: 'Circus Agency' + }, + productName: 'Apply for a juggling licence', + } + }) +} +``` + +If you need more control, use `logo.logotype.html`. This allows you to provide your own HTML which could, for example, contain an SVG logo or image: + +```js +const govukEleventyPlugin = require('@x-govuk/govuk-eleventy-plugin') + +module.exports = function(eleventyConfig) { + eleventyConfig.addPlugin(govukEleventyPlugin, { + header: { + logotype: { + html: `Circus Agency` + }, + productName: 'Apply for a juggling licence', + } + }) +} +``` + +## Update the copyright statement + +By default, the footer shows a link to the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/), and places the website under Crown copyright. + +If these are not right for your website, change: + +- `footer.contentLicence.text` or `footer.contentLicence.html` for the content licence +- `footer.copyright.text` or `footer.copyright.html` for the copyright statement + +For example: + +```js +const govukEleventyPlugin = require('@x-govuk/govuk-eleventy-plugin') + +module.exports = function(eleventyConfig) { + eleventyConfig.addPlugin(govukEleventyPlugin, { + header: { + contentLicence: { + html: 'Licensed under the Example Licence, except where otherwise stated' + }, + copyright: { + text: '© Circus Agency' + }, + } + }) +} +``` + +## Replace the GDS Transport typeface + +A number of design features, including the typeface used, can be changed by overriding SCSS settings. + +Add a `_settings.scss` file to a `/sass/` folder in the input directory (you can change this location using the `scssSettingsPath` option). + +Then, in this SCSS file, override the `$govuk-font-family` setting. For example: + +```scss +$govuk-font-family: system-ui, sans-serif; +``` + +You can also use this file to change other [global SCSS settings provided by GOV.UK Frontend](https://frontend.design-system.service.gov.uk/sass-api-reference/#settings). For example: + +```scss +$govuk-font-family: system-ui, sans-serif; +$govuk-brand-colour: #8822aa; +$govuk-link-colour: #660088; +$govuk-link-hover-colour: #440066; +$govuk-link-visited-colour: #333366; +$govuk-page-width: 1100px; +``` diff --git a/docs/feed.md b/docs/feed.md index a6662aa5..8c07c264 100644 --- a/docs/feed.md +++ b/docs/feed.md @@ -1,6 +1,6 @@ --- layout: sub-navigation -order: 7 +order: 8 title: Adding a feed description: Allow people to subscribe to your posts and read them in a feed reader --- diff --git a/docs/hosting.md b/docs/hosting.md index 1d950dcd..fae37791 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -1,6 +1,6 @@ --- layout: sub-navigation -order: 8 +order: 9 title: Hosting description: Hosting Eleventy websites on services like GitHub Pages. --- diff --git a/docs/layouts.md b/docs/layouts.md index 793faac2..b732fd01 100644 --- a/docs/layouts.md +++ b/docs/layouts.md @@ -1,8 +1,8 @@ --- layout: sub-navigation -order: 3 +order: 4 title: Layouts -description: The plugin offers a number of layouts to match the type of content you want write. +description: Choose a layout to match the type of content you want write. --- {% for page in collections.layout %} diff --git a/docs/markdown-advanced.md b/docs/markdown-advanced.md index 8b9f0796..4fb45dae 100644 --- a/docs/markdown-advanced.md +++ b/docs/markdown-advanced.md @@ -1,6 +1,6 @@ --- layout: sub-navigation -order: 5 +order: 6 title: Advanced Markdown description: Additional Markdown syntax is supported to ensure pages can contain additional elements like tables, code blocks and footnotes. related: diff --git a/docs/markdown.md b/docs/markdown.md index 9c6ba546..a1184913 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -1,6 +1,6 @@ --- layout: sub-navigation -order: 4 +order: 5 title: Markdown description: A lightweight markup language that allows you to add formatting to plain text text documents. related: diff --git a/docs/options.md b/docs/options.md index 89bd087a..d0f26c92 100644 --- a/docs/options.md +++ b/docs/options.md @@ -2,7 +2,7 @@ layout: sub-navigation order: 2 title: Options -description: The plugin has a number of options that allow you to customise the appearance of your website. +description: Customise the appearance and behaviour of your website. --- You can add options to the second parameter of the `addPlugin` function in Eleventy config file. diff --git a/docs/search.md b/docs/search.md index 8c744c24..3c989a3a 100644 --- a/docs/search.md +++ b/docs/search.md @@ -1,6 +1,6 @@ --- layout: sub-navigation -order: 6 +order: 7 title: Adding a site search description: Make it easier for readers to find content on your site. --- diff --git a/docs/tagging.md b/docs/tagging.md index 4de2383d..d2257383 100644 --- a/docs/tagging.md +++ b/docs/tagging.md @@ -1,6 +1,6 @@ --- layout: sub-navigation -order: 7 +order: 9 title: Adding tags description: Use tags to categorise posts and make it easier for readers to browse content on your site. --- diff --git a/eleventy.config.js b/eleventy.config.js index 2d2abb72..a8e82f73 100644 --- a/eleventy.config.js +++ b/eleventy.config.js @@ -64,8 +64,8 @@ module.exports = function (eleventyConfig) { collection .getFilteredByGlob([ 'docs/options.md', - 'docs/layouts.md', - 'docs/markdown.md' + 'docs/design.md', + 'docs/layouts.md' ]) .sort((a, b) => (a.data.order || 0) - (b.data.order || 0)) )