x-govuk / govuk-eleventy-plugin Goto Github PK
View Code? Open in Web Editor NEWWrite documentation using Markdown and publish it using GOV.UK styles.
Home Page: https://x-govuk.github.io/govuk-eleventy-plugin/
License: MIT License
Write documentation using Markdown and publish it using GOV.UK styles.
Home Page: https://x-govuk.github.io/govuk-eleventy-plugin/
License: MIT License
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).
(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.
Here are a few examples with my comments on their respective pros and cons.
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.
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.
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.
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)
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
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 return
ed config object.assetsPath
option (once #110 merged)url
value also need to be set – need to test this.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 locallyTo 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.
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
.
>=8.0.0
as an engine
in package.jsonThe 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.
I believe the breadcrumbs component should be held within a <nav>
element.
In progress over here…
…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/'?
Once govuk-frontend
v4.3.0 is released, can remove the hacky regex the plugin currently uses to achieve the same 🎉
…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 semverThe 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
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".
absoluteUrl(option.url)
not working as expected.eleventy-plugin-rss
dependencyI'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.
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 | node |
---|---|
8.19.3 | v14.18.2 |
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 | node |
---|---|
8.19.3 | v16.19.0 |
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 | node |
---|---|
8.19.3 | v18.13.0 |
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 }
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.