As seen on https://x-govuk.github.io.

Fix needed here:

…and we need to pass this to the items filter so that sidebar navigation respects this value when hosted on GitHub pages.

See: 11ty/eleventy#1647

Currently the Eleventy plugin includes the govuk-prototype-kit package, as well as all the dependencies of that, which I think is probably unnecessary?

This gets included, I think, because govuk-prototype-kit is an optional dependency of govuk-prototype-components.

Perhaps there’s a way to package up govuk-eleventy-plugin so that it doesn't include optional dependencies?

(Spotted this as there’s currently a minor security vulnerability due to a sub-dependency of the prototype kit, which is also affecting any sites using the eleventy plugin).

Compare the breadcrumb and the title:

Posts within a section always display the parent tag first. Which feels redundant given the page heading. Is there any way to hide it on this page but keep it available for the tag page?

(Firstly thanks for making this - this has been extremely useful for a number of projects now)

I'm suspecting that including Mermaid, via https://github.com/KevinGimbel/eleventy-plugin-mermaid, disables syntax highlighting. Specifically the line eleventyConfig.addPlugin(pluginMermaid); when added to eleventy.config.js disables the syntax highlighting from govuk-eleventy-plugin.

There is a reasonably minimal example at https://github.com/michalc/govuk-eleventy-plugin-mermaid. Specifically, a block in index.md should have shell syntax highlighting, and so appear as white text on a black background. But it doesn't, and instead appears as black test on white background.

However, if I remove eleventyConfig.addPlugin(pluginMermaid); from https://github.com/michalc/govuk-eleventy-plugin-mermaid/blob/main/eleventy.config.js#L5 then it works fine

i.e. organisationName ⇒ header.organisationName?

Is there any way to disable breadcrumbs throughout the site?

Hi 👋 ,

Firstly, thanks for a great plugin - it's been really useful for a few projects, e.g. https://pg-bulk-ingest.docs.trade.gov.uk/ and https://stream-unzip.docs.trade.gov.uk/

One thing though that I'm not quite sure how to do is integrating govuk-eleventy-plugin / 11ty with some sort of system for generating API documentation from source code, and specifically for Python, say using https://github.com/pdoc3/pdoc.

I wonder if anyone has any tips/suggestions on how to tackle this?

Thanks!

Michal

The Becoming a teacher design history, which covers 7 services (depending how you count them) is now old enough and big enough that finding posts can be quite hard.

To resolve this, I’ve added support for tags - which means there’s now a new Tags page as well as pages for individual tags, and links to these from the individual posts.

Getting this to work was more fiddly than I expected, as whilst Eleventy already supports "tags" metadata and creates a collection for each tag, collections are also used for other things, including a special all collection, and we were also already (mis?)using tags to group together posts from the different services. You also don't get tag pages by default, but need to set this up.

Now that it’s done though, I think it’s proving to be quite useful, and we’d like to improve it in future by possibly having additional tag pages that are scoped by service (as well as the global ones), and to support tags within the "search" feature at the top. The tag pages are also currently missing pagination controls.

I think this feature would be a good candidate for upstreaming into the govuk-eleventy-plugin?

The search layout does not display dates correctly from the page data for instances where a command such as git Last Modified is passed in, as was introduced in 11ty in 1.0.1.

Rather than displaying the rendered date, the string cannot be parsed so this results in the date not rendering in the layout:

Expected result:

"date": "2023-04-27T13:39:22.000Z",
    "dateString": "27 April 2023",  

Actual result:

"date": null,
"dateString": "Invalid DateTime",

The rendered date can instead be retrieved from the page object in the collection item.

Specifically, I want to override the og:image.

Recently, I have been looking at options to present (relatively) short, government related, open datasets in both human readable (Design System) and machine readable (multiple formats) way. I'm looking for something that doesn't require a dedicated service, something simple to host, but also something simple to contribute to.

Examples

Here are a few examples with my comments on their respective pros and cons.

Government organisations on github

The community section on government.github.com is based on a dataset which can be updated by creating a pull request to a yaml file. This works well for two level hierarchy where the entities have single attribute - the account name. Anything more might get out of hand very quickly. The website doesn't offer an easy way to process the data automatically, you have to use the raw data file in the github repo.

Congress Legislators

There is a github repo with published data on Congress Legislators (US public sector, but the same principle applies to us) is another example. They have only a github repo with yaml files. There is techy readable but not an average person readable. The files can be consumed by automated processes but only by referencing raw file paths on github.

Services list maintained by x-govuk

The x-govuk list of digital services. The simple list of services in Design System is available, some information about what it is, how to contribute is available. Data can be more complex as each entity is in a json file. However, the automated processing is more difficult as multiple files have to be navigated. Replicating this solution for another dataset would require copying a lot of boilerplate code - using eleventy plugin would be a better option.

Proposal

I would like to extend the work you have done with govuk-eleventy-plugin and offer a simplified way to create a standard data-product page, a data-collection page and perhaps a data-detail page. I would like to keep the data in CSVW format which is then automatically translated into static pages with RDFa annotations as well as other data formats (e.g. RDF in Turtle, JSON-LD)

Questions

• Would you be open to addition of such templates?
• I'm happy to do the work, but I will need some support. Would you be happy to offer some guidance regarding eleventy and govuk-eleventy-plugin? Depending on the answer to the first question this might be either to contribute templates within the project or to build a separate plugin that extends govuk-eleventy-plugin.

Eleventy package @11ty/eleventy starting from v2.0.0 disabled the indented code blocks in Markdown by default.
This means that text blocks indented with 4 or more spaces won't be rendered as a code block anymore.

The indented code block behaviour can be changed by configuring the eleventy package (see: https://www.11ty.dev/docs/languages/markdown/#indented-code-blocks)

Alternatively, the documentation can be amended to omit the indented text blocks, and to add a breaking change notice.

Support defintion lists for extended Markdown syntax:

Definition term
: Definition description

• Requirements
• Installation
• Configuration
• Configuration options
• Layouts
• Overriding layouts
• Basic Markdown syntax
• Extended Markdown syntax
• Enabling search (creating a search index and sitemap)
• Adding additional stylesheets
• Navigation

Related content should align with main content, not title. Aligning with the main content matches the way GOV.UK displays articles.

Expected position	Current position	GOV.UK

Hosting an Eleventy-powered site on GitHub pages is possible but requires a bit of fiddling if hosting at a sub-folder (i.e. https://username.github.io/reponame):

• pathPrefix option has to be provided, both in the plugin options, and Eleventy’s returned config object.
• Need to update assetsPath option (once #110 merged)
• Does the url value also need to be set – need to test this. No - only needed to have a full canonical URL for Open Graph data
• Testing for the presence of process.env.GITHUB_ACTIONS means you can create a config that only appends pathPrefix (and url) when the site is being deployed to and hosted on GitHub Pages, but not when running locally
• You also need to create a deploy workflow (like the one for this project’s own documentation), and update your repo settings to use GitHub Actions to deploy pages.

To make it clearer that this is not a GDS-owned or endorsed project, move the package under the @x-govuk organisation when publishing the next major version.

Within the product layout, the masthead component xGovukMasthead is not contained within a landmark.

Within our project, this is triggering this automated accessibility check.

Proposal

I believe both the masthead and the content should both be contained within a main landmark. Currently, on the product layout, only the content is contained within the main landmark.

Using the plugin in with versions of npm below 8.0.0 prevents the plugin being installed, as Rollup has a hard dependency on npm >=8.0.0.

• List npm 8 as a dependency in the README
• List npm 8 as a dependency in the documentation
• Add npm >=8.0.0 as an engine in package.json

The breadcrumbs component govukBreadcrumbs that is used in several layouts are not contained within a landmark.

Within our project, this is triggering this automated accessibility check.

Proposal

I believe the breadcrumbs component should be held within a <nav> element.

In progress over here…

Compared with:

…possibly sharing/linking to a table of options that are common to all pages.

…because it’s weird that when you navigate the layout documentation, you get different page layouts.

govuk-frontend supports variable asset path at saas compilation time: https://frontend.design-system.service.gov.uk/sass-api-reference/#govuk-assets-path, however no value is supplied at sass compilation time, meaning that css contains URLs of ("/assets/..."), which only work for assets hosted at root /.

When using hosting such as GitLab Pages, sites are hosted at a sub-directory e.g. pages.gitlab.io/mygroup/myrepository/ - this includes all bundled assets, so URL references in css would need to be URL("mygroup/myrepository/assets/...") to be found.

Would it be possible to populate $govuk-assets-path via a new option value, or potentially using `pathPrefix + '/assets/'?

https://cln.sh/R0CwRDGx

Once govuk-frontend v4.3.0 is released, can remove the hacky regex the plugin currently uses to achieve the same 🎉

alphagov/govuk-frontend#1920

…because marked.js 🙄

Might pay to move adding typographic replacements to govuk-markdown renderer.

See https://www.11ty.dev/docs/plugins/html-base/

This would solve a lot of issues with X-GOVUK projects, which are hosted at sub-folders, and caught us out with the recent updates to the Prototype Components documentation site.

Our Dependabot scans have raised the below (this is the case for 5.0.3 as well)

Dependabot cannot update semver to a non-vulnerable version
The latest possible version that can be installed is 5.7.1 because of the following conflicting dependencies:

@x-govuk/[email protected] requires semver@^5.7.1 via a transitive dependency on [email protected]
@x-govuk/[email protected] requires semver@~7.0.0 via a transitive dependency on [email protected]
No patched version available for semver

The earliest fixed version is 7.5.2.

There is an open PR for a fix for nodemon - remy/nodemon#2118
simple-update-notifier has fix in release v2.0.0 - https://github.com/alexbrazier/simple-update-notifier/releases/tag/v2.0.0

See https://nvd.nist.gov/vuln/detail/CVE-2022-25883

On posts like this one, the following HTML is being rendered in the <head>:

<meta property="og:image" content="https://x-govuk.github.io/assets/posts/introduction/x-govuk-logo.png">
<meta property="og:image:alt" content="The GOV.UK crown viewed from above.">
<meta property="og:image" content="https://x-govuk.github.io//images/govuk-opengraph-image.png">

The second og:image is the default one (govuk-opengraph-image.png), which shouldn’t be being rendered at all.

I’d not noticed this before, I guess because most social media platforms will select the first tag if there’s a duplicate, but BlueSky seems to pick the second one. (Separately, there’s a bug which is that the second default URL contains a double // which means it’s broken).

Going to do some investigation into this...

If there is a version conflict between a govuk-eleventy-plugin dependency and the host project's dependencies, npm will include the expected version in a nested node_modules folder. https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/lib/nunjucks.js doesn't check for this and register's the host project's version. If this is missing any of the components the eleventy plugin uses the site fails to build with template not found errors.

Seems likely that the default value for dir.input doesn’t get passed in eleventyConfig, so plugin errors without this value set.

You’re welcome to use the plugin even if your service isn’t considered part of GOV.UK, but your site or service 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

How can I completely remove all GOV.UK branding ? Do you have an example eleventy.config.js?

I tried setting several options from https://x-govuk.github.io/govuk-eleventy-plugin/options/ but the typeface remains GDS Transport and the title element still contains "GOV.UK".

• Need to account for either full or absolute URLs being provided in plugin or page configs for some values. absoluteUrl(option.url) not working as expected.
• Potentially opportunity to remove eleventy-plugin-rss dependency
• It’s complicated :-/

I'm a newbie to Eleventy, trying to use this plugin for a non-profit think tank website. I want to know how you enabled the sticky left-side menu layout as is the case on this gov.uk page. Can I implement that feature by configuring options in your plugin?

The 11ty docs suggest overriding the default Nunjucks configuration with a stanza like

eleventyConfig.setNunjucksEnvironmentOptions({
  dev: true
});

in eleventy.config.js. (This example was to set a flag which I was hoping would tell me what was wrong with my template, ho hum.)

However, the way that the plugin configures Nunjucks in https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/lib/nunjucks.js#L36 this doesn't seem to be possible. A default configuration is obviously essential, but it would be nice if this just worked.

See 11ty/eleventy#1612 (comment)

With virtual templates defined in the plugin, consumers no longer need to worry about configuring the path to the layouts folder in node_modules, and it should hopefully be easier to extend (instead of overwrite) plugin-provided layouts.

https://x-govuk.github.io/govuk-eleventy-plugin/get-started/ says the following:

I'm not sure exactly how this should work, but I feel like it should list some layouts here, rather than "0 layouts".

Prior to v6.0, the plugin provided a header.organisationName option to change the GOV.UK shown in the header. This was replaced with header.logotype options, however the option was unintentionally still being referenced in the document title.

#298 added a new option, titleSuffix, but kept the header.organisationName option to maintain backwards compatibility (even though the upgrade notes stated that this option was no longer supported). We’ll remove the older option in the next major version as a breaking change.

cc @frankieroberto

Hello 👋

The __govuk.svg file in the header component is using the old crown logo.

Can we update this to use the new crown logo?

Thanks,
Cormac

@paulrobertlloyd I've merged some dependabot alerts and manually updated some dependencies in order to resolve some security alerts (which are pretty low risk for a static site but annoying nonetheless).

Worth doing a v5.0.4 release for? (This'll also fix any security alerts on downstream sites which use this plugin).

The page that lists all posts using a specific tag does not display dates correctly.

On tag pages such as tags/layout/, dates under each page do not display.

Looking to upgrade to [3.0.3] after seeing #60 but having an issue. Think it might be my config, but unsure.

I'm using this with the design-history-template, should I raise it there instead?

package.json

    "govuk-eleventy-plugin": "^3.0.3",

I ran npm run start

> [email protected] start
> eleventy --serve --quiet

[11ty] Problem writing Eleventy templates: (more in DEBUG output)
[11ty] 1. Having trouble writing template: "public/example-post/index.html" (via EleventyTemplateError)
[11ty] 2. (./app/_layouts/post.njk) [Line 11, Column 26]
[11ty]   Error: Unable to call `appDocumentFooter`, which is undefined or falsey (via Template render error)
[11ty] 
[11ty] Original error stack trace: Template render error: (./app/_layouts/post.njk) [Line 11, Column 26]
[11ty]   Error: Unable to call `appDocumentFooter`, which is undefined or falsey
[11ty]     at Object._prettifyError (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/lib.js:36:11)
[11ty]     at /Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:563:19
[11ty]     at eval (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:148:12)
[11ty]     at eval (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:287:12)
[11ty]     at b_content (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:138:3)
[11ty]     at eval (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:286:28)
[11ty]     at b_beforeContent (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:42:1)
[11ty]     at b_main (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:273:34)
[11ty]     at eval (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:147:83)
[11ty]     at b_header (eval at _compile (/Users/alexhedley/govuk-design-history-template/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:378:1)
[11ty] Wrote 0 files in 0.66 seconds (v1.0.2)

I was on an older version of node so I've upgraded to various versions to try it out.

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '[email protected]',
npm WARN EBADENGINE   required: { node: '^16.0.0' },
npm WARN EBADENGINE   current: { node: 'v14.18.2', npm: '8.19.3' }
npm WARN EBADENGINE }
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '[email protected]',
npm WARN EBADENGINE   required: { node: '^16.0.0' },
npm WARN EBADENGINE   current: { node: 'v14.18.2', npm: '8.19.3' }
npm WARN EBADENGINE }
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '[email protected]',
npm WARN EBADENGINE   required: { node: '>=16.0.0' },
npm WARN EBADENGINE   current: { node: 'v14.18.2', npm: '8.19.3' }
npm WARN EBADENGINE }
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '[email protected]',
npm WARN EBADENGINE   required: { node: '>=16.0.0' },
npm WARN EBADENGINE   current: { node: 'v14.18.2', npm: '8.19.3' }
npm WARN EBADENGINE }

npm WARN deprecated [email protected]: this library is no longer supported
npm WARN deprecated [email protected]: Please upgrade  to version 7 or higher.  Older versions may use Math.random() in certain circumstances, which is known to be problematic.  See https://v8.dev/blog/math-random for details.
npm WARN deprecated [email protected]: this package is now deprecated
npm WARN deprecated [email protected]: request has been deprecated, see https://github.com/request/request/issues/3142

npm WARN deprecated [email protected]: this library is no longer supported
npm WARN deprecated [email protected]: Please upgrade  to version 7 or higher.  Older versions may use Math.random() in certain circumstances, which is known to be problematic.  See https://v8.dev/blog/math-random for details.
npm WARN deprecated [email protected]: this package is now deprecated
npm WARN deprecated [email protected]: request has been deprecated, see https://github.com/request/request/issues/3142

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '[email protected]',
npm WARN EBADENGINE   required: { node: '^16.0.0' },
npm WARN EBADENGINE   current: { node: 'v18.13.0', npm: '8.19.3' }
npm WARN EBADENGINE }
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '[email protected]',
npm WARN EBADENGINE   required: { node: '^16.0.0' },
npm WARN EBADENGINE   current: { node: 'v18.13.0', npm: '8.19.3' }
npm WARN EBADENGINE }

This one has been bothering me for ages; might be the result of a change in underline styles within the header in upstream govuk-frontend.