From e666e623ac18051716a2e619685b02ba7719901c Mon Sep 17 00:00:00 2001 From: Paul Robert Lloyd Date: Sat, 23 Dec 2023 18:34:30 +0000 Subject: [PATCH] Use govukTable for options tables --- docs/assets/application.scss | 13 ++ docs/layouts/collection.md | 25 ++- docs/layouts/post.md | 97 +++++++++-- docs/layouts/product.md | 49 +++++- docs/layouts/sub-navigation.md | 19 ++- docs/options.md | 296 ++++++++++++++++++++++++++------- eleventy.config.js | 1 + 7 files changed, 407 insertions(+), 93 deletions(-) create mode 100644 docs/assets/application.scss diff --git a/docs/assets/application.scss b/docs/assets/application.scss new file mode 100644 index 00000000..b3d3272c --- /dev/null +++ b/docs/assets/application.scss @@ -0,0 +1,13 @@ +@media screen and (min-width: 800px) { + .app-prose-scope .govuk-table { + display: table; + } + + .app-prose-scope .govuk-table__header:first-of-type { + width: 30%; + } + + .app-prose-scope .govuk-table__cell *:last-child { + margin-bottom: 0; + } +} diff --git a/docs/layouts/collection.md b/docs/layouts/collection.md index fa270b0f..ab700745 100644 --- a/docs/layouts/collection.md +++ b/docs/layouts/collection.md @@ -19,7 +19,24 @@ Page content In addition to [common front matter options](/layouts#common-front-matter-options), this layout accepts the following options: -| Name | Type | Description | -| :-------------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **pagination** | object | **Required.** Pages to show in the paginated list. Learn more about [pagination](https://www.11ty.dev/docs/pagination/) in the documentation for Eleventy. | -| **paginationHeading** | string | Heading for the list of paginated pages. | +{% from "govuk/components/table/macro.njk" import govukTable %} +{{ govukTable({ + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "pagination" }, + { text: "object" }, + { text: "**Required.** Pages to show in the paginated list. Learn more about [pagination](https://www.11ty.dev/docs/pagination/) in the documentation for Eleventy." | markdown } + ], + [ + { text: "paginationHeading" }, + { text: "string" }, + { text: "Heading for the list of paginated pages." } + ] + ] +}) }} diff --git a/docs/layouts/post.md b/docs/layouts/post.md index a53aeb6b..6a486363 100644 --- a/docs/layouts/post.md +++ b/docs/layouts/post.md @@ -19,19 +19,84 @@ Page content In addition to [common front matter options](/layouts#common-front-matter-options), this layout accepts the following options: -| Name | Type | Description | -| :----------------------- | :------------------------- | :------------------------------------------------------------------------------------------- | -| **author** | string or object | Post author. | -| **author.name** | string | Name of post author. Overrides any single value given for author. | -| **author.url** | string | URL for website of post author. | -| **authors** | array | Post authors. Overrides any value(s) given for author. | -| **authors.name** | string | Name of post author. | -| **authors.url** | string | URL for website of post author. | -| **date** | string | Date post was published using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601). | -| **image** | object | Image shown above post content. | -| **image.src** | string | Path to post image. | -| **image.alt** | string | Alternative text for post image. | -| **image.caption** | string | Caption shown below post image. | -| **image.opengraphImage** | boolean | Whether image should also be used as the page’s Open Graph share image. | -| **modified** | string | Date post was updated using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601). | -| **tags** | Array | List of tags post relates to | +{% from "govuk/components/table/macro.njk" import govukTable %} +{{ govukTable({ + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "author" }, + { text: "string or object" }, + { text: "Post author." } + ], + [ + { text: "author.name" }, + { text: "string" }, + { text: "Name of post author. Overrides any single value given for author." } + ], + [ + { text: "author.url" }, + { text: "string" }, + { text: "URL for website of post author." } + ], + [ + { text: "authors" }, + { text: "Array" }, + { text: "Post authors. Overrides any value(s) given for author." } + ], + [ + { text: "authors.name" }, + { text: "string" }, + { text: "Name of post author." } + ], + [ + { text: "authors.url" }, + { text: "string" }, + { text: "URL for website of post author." } + ], + [ + { text: "date" }, + { text: "string" }, + { text: "Date post was published using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)." | markdown } + ], + [ + { text: "image" }, + { text: "object" }, + { text: "Image shown above post content." } + ], + [ + { text: "image.src" }, + { text: "string" }, + { text: "Path to post image." } + ], + [ + { text: "image.alt" }, + { text: "string" }, + { text: "Alternative text for post image." } + ], + [ + { text: "image.caption" }, + { text: "string" }, + { text: "Caption shown below post image." } + ], + [ + { text: "image.opengraphImage" }, + { text: "boolean" }, + { text: "Whether image should also be used as the page’s Open Graph share image." } + ], + [ + { text: "modified" }, + { text: "string" }, + { text: "Date post was updated using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)." | markdown } + ], + [ + { text: "tags" }, + { text: "Array" }, + { text: "List of tags post relates to." } + ] + ] +}) }} diff --git a/docs/layouts/product.md b/docs/layouts/product.md index 0bd33336..60bffdf4 100644 --- a/docs/layouts/product.md +++ b/docs/layouts/product.md @@ -21,11 +21,44 @@ Page content In addition to [common front matter options](/layouts#common-front-matter-options), this layout also accepts the following options: -| Name | Type | Description | -| :------------------- | :----- | :------------------------------------------------------------------------------ | -| **startButton** | string | Start button. Appears below the title and any description. | -| **startButton.text** | string | Text for the start button. Default is `'Get started'`. | -| **startButton.href** | string | The URL that the start button should link to. | -| **image** | object | Product image. Appears to the right of the page title, and is hidden on mobile. | -| **image.src** | string | Path to product image. | -| **image.alt** | string | Alternative text for product image. | +{% from "govuk/components/table/macro.njk" import govukTable %} +{{ govukTable({ + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "startButton" }, + { text: "object" }, + { text: "Start button. Appears below the title and any description." } + ], + [ + { text: "startButton.text" }, + { text: "string" }, + { text: "Text for the start button (default is `'Get started'`)." | markdown } + ], + [ + { text: "startButton.href" }, + { text: "string" }, + { text: "URL or page the start button should link to." } + ], + [ + { text: "image" }, + { text: "object" }, + { text: "Product image. Appears to the right of the page title, and is hidden on mobile." } + ], + [ + { text: "image.src" }, + { text: "string" }, + { text: "Path to product image." } + ], + [ + { text: "image.alt" }, + { text: "string" }, + { text: "Alternative text for product image." } + ] + ] +}) }} diff --git a/docs/layouts/sub-navigation.md b/docs/layouts/sub-navigation.md index 3a52533b..dfab9986 100644 --- a/docs/layouts/sub-navigation.md +++ b/docs/layouts/sub-navigation.md @@ -21,6 +21,19 @@ Page content In addition to [common front matter options](/layouts#common-front-matter-options), this layout also accepts the following options: -| Name | Type | Description | -| :------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **sectionKey** | string | Parent navigation key (usually a page title) to show items below in the sub navigation. Default is `homeKey` value provided in [plugin options](/options). | +{% from "govuk/components/table/macro.njk" import govukTable %} +{{ govukTable({ + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "sectionKey" }, + { text: "string" }, + { text: "Parent navigation key (usually a page title) to show items below in the sub navigation. Default is `homeKey` value provided in [plugin options](/options)." | markdown } + ] + ] +}) }} diff --git a/docs/options.md b/docs/options.md index ee56ab8f..faf42c8f 100644 --- a/docs/options.md +++ b/docs/options.md @@ -15,78 +15,250 @@ const govukEleventyPlugin = require('@x-govuk/govuk-eleventy-plugin') module.exports = function(eleventyConfig) { eleventyConfig.addPlugin(govukEleventyPlugin, { header: { - productName: 'Apply for a juggling licence API docs', + productName: 'Apply for a juggling licence', } }) } ``` -| Name | Type | Description | -| :-------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **icons.mask** | string | Override default GOV.UK SVG mask icon. | -| **icons.shortcut** | string | Override default GOV.UK favicon. | -| **icons.touch** | string | Override default GOV.UK touch icon. | -| **opengraphImageUrl** | string | URL for default Open Graph share image. | -| **themeColour** | string | Browser theme colour. Must be a hex value, i.e. `#0b0c0c` | -| **headingPermalinks** | boolean | Add links to headings, making it easier to share sections of a page. | -| **homeKey** | string | Label to use for first item in pagination and key to use when referring to the home page for [`eleventyNavigation.parent`](https://www.11ty.dev/docs/plugins/navigation/). Default is `'Home'` | -| **parentSite** | object | Website to show as first item in breadcrumbs. | -| **parentSite.url** | string | URL for parent site. | -| **parentSite.name** | string | Name of parent site. | -| **scssSettingsPath** | string | Path to SCSS file, relative to input directory, containing [GOV.UK Frontend settings](https://frontend.design-system.service.gov.uk/sass-api-reference/). Defaults to `{dir.input}/sass/_settings.scss`. | -| **stylesheets** | Array | Additional stylesheets to load after application styles. | -| **url** | string | The URL of your website. Optional, but required to have valid canonical URLs in Open Graph meta data. | -| **header** | object | See [header](#options-for-header). | -| **navigation** | object | See [navigation](#options-for-navigation). | -| **footer** | object | See [footer](#options-for-footer). | +{% from "govuk/components/table/macro.njk" import govukTable %} +{{ govukTable({ + caption: "Plugin options", + captionClasses: "govuk-table__caption--l", + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "icons" }, + { text: "object" }, + { text: "Override GOV.UK icons." } + ], + [ + { text: "icons.mask" }, + { text: "string" }, + { text: "Override GOV.UK SVG mask icon." } + ], + [ + { text: "icons.shortcut" }, + { text: "string" }, + { text: "Override GOV.UK favicon." } + ], + [ + { text: "icons.touch" }, + { text: "string" }, + { text: "Override GOV.UK touch icon." | markdown } + ], + [ + { text: "opengraphImageUrl" }, + { text: "string" }, + { text: "URL for default Open Graph share image." } + ], + [ + { text: "headingPermalinks" }, + { text: "boolean" }, + { text: "Add links to headings, making it easier to share sections of a page (default is `false`)." | markdown } + ], + [ + { text: "homeKey" }, + { text: "string" }, + { text: "First item in pagination and key to use when referring to the home page for [`eleventyNavigation.parent`](https://www.11ty.dev/docs/plugins/navigation/) (default is `'Home'`)." | markdown } + ], + [ + { text: "parentSite" }, + { text: "object" }, + { text: "Website to show as first item in breadcrumbs." } + ], + [ + { text: "parentSite.url" }, + { text: "string" }, + { text: "URL for parent site." } + ], + [ + { text: "parentSite.name" }, + { text: "string" }, + { text: "Name of parent site." } + ], + [ + { text: "scssSettingsPath" }, + { text: "string" }, + { text: "Path to SCSS file, relative to input directory, containing [GOV.UK Frontend settings](https://frontend.design-system.service.gov.uk/sass-api-reference/) (default is `{dir.input}/sass/_settings.scss`)." | markdown } + ], + [ + { text: "stylesheets" }, + { text: "Array" }, + { text: "Additional stylesheets to load after application styles." } + ], + [ + { text: "themeColour" }, + { text: "string" }, + { text: "Browser theme colour. Must be a hex value, i.e. `#0b0c0c`" | markdown } + ], + [ + { text: "url" }, + { text: "string" }, + { text: "The URL of your website. Optional, but required to have valid canonical URLs in Open Graph meta data." } + ], + [ + { text: "header" }, + { text: "object" }, + { text: "See [header options](#header-options)." | markdown } + ], + [ + { text: "navigation" }, + { text: "object" }, + { text: "See [navigation options](#navigation-options)." | markdown } + ], + [ + { text: "footer" }, + { text: "object" }, + { text: "See [footer options](#footer-options)." | markdown } + ] + ] +}) }} -## Options for header +## Header options -In addition to the [options available for the header component](https://design-system.service.gov.uk/components/header/), the following options can also be set: +In addition to the [options available for the header component](https://design-system.service.gov.uk/components/header/), the following options can also be set for `header`: -| Name | Type | Description | -| :---------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **homepageUrl** | string | URL organisation name is linked to. Default is `'/'` | -| **logotype** | object | Logo that appears in the header. If no value is provided, the GOV.UK logo is shown. | -| **logotype.text** | string | Text to show instead of the GOV.UK logo. This text will appear bold. If `html` is set, this is not required. If `html` is provided, the `text` option will be ignored. | -| **logotype.html** | string | If `text` is set, this is not required. If `html` is provided, the `text` option will be ignored. | -| **productName** | string | Product name that appears after the organisation name. Default is `false`. | -| **search** | object | See [header.search](#options-for-header.search). | +{{ govukTable({ + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "homepageUrl" }, + { text: "string" }, + { text: "URL organisation name is linked to (default is `'/'`)." | markdown } + ], + [ + { text: "logotype" }, + { text: "object" }, + { text: "Logo that appears in the header. If no value is provided, the GOV.UK logo is shown." } + ], + [ + { text: "logotype.text" }, + { text: "string" }, + { text: "Text to show instead of the GOV.UK logo. This text will appear bold. If `html` is set, this is not required. If `html` is provided, the `text` option will be ignored." | markdown } + ], + [ + { text: "logotype.html" }, + { text: "string" }, + { text: "If `text` is set, this is not required. If `html` is provided, the `text` option will be ignored." | markdown } + ], + [ + { text: "productName" }, + { text: "string" }, + { text: "Product name that appears after the organisation name (default is `false`)." | markdown } + ], + [ + { text: "search" }, + { text: "object" }, + { text: "Search box that appears in the header." } + ], + [ + { text: "search.label" }, + { text: "string" }, + { text: "Text to show in the search field (default is `'Search site'`)."| markdown } + ], + [ + { text: "search.indexPath" }, + { text: "string" }, + { text: "Path to search index file." } + ], + [ + { text: "search.sitemapPath" }, + { text: "string" }, + { text: "Path to sitemap page." } + ] + ] +}) }} -### Options for header.search +## Navigation options -Options for site search. See [adding a site search](../search). +{{ govukTable({ + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "visuallyHiddenTitle" }, + { text: "string" }, + { text: "Hidden title for navigation." } + ], + [ + { text: "items" }, + { text: "Array" }, + { text: "An array of navigation links to show." } + ], + [ + { text: "items[].text" }, + { text: "string" }, + { text: "**Required**. Navigation link text." | markdown } + ], + [ + { text: "items[].href" }, + { text: "string" }, + { text: "**Required**. Navigation link `href` attribute." | markdown } + ], + [ + { text: "items[].classes" }, + { text: "string" }, + { text: "Classes to add to the navigation item." } + ] + ] +}) }} -| Name | Type | Description | -| :-------------- | :----- | :----------------------------------------------------------------------------- | -| **label** | string | Text to show in the search field. Default is `'Search site'` | -| **indexPath** | string | Path to search index file. If set, a search input will be shown in the header. | -| **sitemapPath** | string | Path to sitemap page. | +## Footer options -## Options for navigation +In addition to the [options available for the footer component](https://design-system.service.gov.uk/components/header/), the following options can also be set for `footer`: -| Name | Type | Description | -| :---------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------- | -| **visuallyHiddenTitle** | string | Hidden title for header navigation. | -| **items** | Array | An array of navigation links to shown within the header navigation. See [navigation.items](#options-for-navigation.items). | - -### Options for navigation.items - -| Name | Type | Description | -| :---------- | :----- | :----------------------------------------------------------------- | -| **text** | string | **Required**. Text of the navigation link. | -| **href** | array | **Required**. The value of the navigation link’s `href` attribute. | -| **classes** | string | Classes to add to the navigation item. | - -## Options for footer - -In addition to the [options available for the footer component](https://design-system.service.gov.uk/components/footer/), the following options can also be set: - -| Name | Type | Description | -| :---------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **contentLicence** | object | Licence description. If no value is provided, the OGL logo is shown alongside the words `All content is available under the Open Government Licence v3.0, except where otherwise stated`. | -| **contentLicence.text** | string | If `html` is set, this is not required. If `html` is provided, the `text` option will be ignored. | -| **contentLicence.html** | string | If `text` is set, this is not required. If `html` is provided, the `text` option will be ignored. | -| **copyright** | object | Copyright statement. If no value is provided, `© Crown copyright` is displayed below an image of the Royal Coat of Arms. | -| **copyright.text** | string | If `html` is set, this is not required. If `html` is provided, the `text` option will be ignored. | -| **copyright.html** | string | If `text` is set, this is not required. If `html` is provided, the `text` option will be ignored. | +{{ govukTable({ + firstCellIsHeader: true, + head: [ + { text: "Name" }, + { text: "Type" }, + { text: "Description" } + ], + rows: [ + [ + { text: "contentLicence" }, + { text: "object" }, + { text: "Licence description. If no value is provided, the OGL logo is shown alongside the words `All content is available under the Open Government Licence v3.0, except where otherwise stated`." | markdown } + ], + [ + { text: "contentLicence.text" }, + { text: "string" }, + { text: "If `html` is set, this is not required. If `html` is provided, the `text` option will be ignored." | markdown } + ], + [ + { text: "contentLicence.html" }, + { text: "string" }, + { text: "If `text` is set, this is not required. If `html` is provided, the `text` option will be ignored." | markdown } + ], + [ + { text: "copyright" }, + { text: "object" }, + { text: "Copyright statement. If no value is provided, `© Crown copyright` is displayed below an image of the Royal Coat of Arms." | markdown } + ], + [ + { text: "copyright.text" }, + { text: "string" }, + { text: "If `html` is set, this is not required. If `html` is provided, the `text` option will be ignored." | markdown } + ], + [ + { text: "copyright.html" }, + { text: "string" }, + { text: "If `text` is set, this is not required. If `html` is provided, the `text` option will be ignored." | markdown } + ] + ] +}) }} diff --git a/eleventy.config.js b/eleventy.config.js index 9fa6940c..bca9641d 100644 --- a/eleventy.config.js +++ b/eleventy.config.js @@ -20,6 +20,7 @@ module.exports = function (eleventyConfig) { url: process.env.GITHUB_ACTIONS && 'https://x-govuk.github.io/govuk-eleventy-plugin/', + stylesheets: ['/assets/application.css'], header: { logotype: 'x-govuk', productName: 'Eleventy Plugin',