@x-govuk/nhsuk-eleventy-plugin 1.0.0

package/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2025 X-GOVUK
+Copyright (c) 2019 NHS Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# NHS.UK Eleventy Plugin • [![test](https://github.com/x-govuk/nhsuk-eleventy-plugin/actions/workflows/test.yml/badge.svg)](https://github.com/x-govuk/nhsuk-eleventy-plugin/actions/workflows/test.yml)
+
+Build documentation websites using Markdown and NHS.UK styles.
+
+## Requirements
+
+- [Node.js](https://nodejs.org) v22 or later
+- [Eleventy](https://www.11ty.dev) v3 or later
+
+## Installation
+
+`npm install @x-govuk/nhsuk-eleventy-plugin`
+
+## Usage
+
+```js
+import { nhsukEleventyPlugin } from '@x-govuk/nhsuk-eleventy-plugin'
+
+export default function(eleventyConfig) {
+  eleventyConfig.addPlugin(nhsukEleventyPlugin, {
+    // Options
+  })
+}
+```
+
+Learn more about how to [get started](https://x-govuk.github.io/nhsuk-eleventy-plugin/get-started/) and which [options you can provide](https://x-govuk.github.io/nhsuk-eleventy-plugin/get-started/options/).
+
+## Releasing a new version
+
+`npm run release`
+
+This command will ask you what version you want to use. It will then publish a new version on NPM, create and push a new git tag and then generate release notes ready for posting on GitHub.
+
+> [!NOTE]
+> Releasing a new version requires permission to publish packages to the `@x-govuk` organisation.

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@x-govuk/nhsuk-eleventy-plugin",
+  "version": "1.0.0",
+  "description": "Write documentation using Markdown and publish it using NHS.UK styles",
+  "keywords": [
+    "nhsuk",
+    "healthcare",
+    "eleventy",
+    "eleventy-plugin"
+  ],
+  "homepage": "https://x-govuk.github.io/nhsuk-eleventy-plugin/",
+  "bugs": {
+    "url": "git+https://github.com/x-govuk/nhsuk-eleventy-plugin/issues"
+  },
+  "contributors": [
+    {
+      "name": "Paul Robert Lloyd",
+      "url": "https://paulrobertlloyd.com"
+    }
+  ],
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x-govuk/nhsuk-eleventy-plugin.git"
+  },
+  "scripts": {
+    "prebuild": "rimraf _site",
+    "postbuild": "npm run build:example",
+    "build": "eleventy",
+    "build:example": "eleventy --config=example.config.js",
+    "predev": "npm run build",
+    "dev": "eleventy --serve --watch",
+    "dev:example": "eleventy --config=example.config.js --serve --watch",
+    "start": "eleventy --serve",
+    "lint:prettier": "prettier . --check",
+    "lint:prettier:fix": "prettier . --write",
+    "lint:js": "eslint '**/*.js'",
+    "lint:js:fix": "eslint '**/*.js' --fix",
+    "lint:scss": "stylelint '**/*.scss'",
+    "lint:scss:fix": "stylelint '**/*.scss' --fix",
+    "lint": "npm run lint:prettier && npm run lint:js && npm run lint:scss",
+    "lint:fix": "npm run lint:prettier:fix && npm run lint:js:fix && npm run lint:scss:fix",
+    "test": "node --test",
+    "coverage": "node --test --experimental-test-coverage",
+    "release": "np"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@11ty/eleventy": "^3.0.0",
+    "@11ty/eleventy-navigation": "^1.0.0",
+    "@rollup/plugin-commonjs": "^28.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@x-govuk/govuk-eleventy-plugin": "^8.0.0",
+    "accessible-autocomplete": "^3.0.1",
+    "deepmerge": "^4.2.2",
+    "markdown-it-abbr": "^2.0.0",
+    "markdown-it-anchor": "^9.0.0",
+    "markdown-it-attribution": "^0.1.4",
+    "markdown-it-attrs": "^4.3.1",
+    "markdown-it-deflist": "^3.0.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-github-alerts": "^1.0.0",
+    "markdown-it-govuk": "^0.7.0",
+    "markdown-it-image-figures": "^2.0.0",
+    "markdown-it-ins": "^4.0.0",
+    "markdown-it-mark": "^4.0.0",
+    "markdown-it-sub": "^2.0.0",
+    "markdown-it-sup": "^2.0.0",
+    "markdown-it-table-of-contents": "^0.9.0",
+    "nhsuk-frontend": "^10.0.0",
+    "rimraf": "^6.0.0",
+    "rollup": "^4.1.0",
+    "sass": "^1.45.1"
+  },
+  "devDependencies": {
+    "@x-govuk/eslint-config": "^0.0.1",
+    "@x-govuk/nhsuk-eleventy-plugin": "file:./",
+    "np": "^10.0.0",
+    "prettier": "^3.1.0",
+    "stylelint": "^16.0.0",
+    "stylelint-config-gds": "^2.0.0",
+    "stylelint-order": "^7.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "module-sync": "./src/index.js",
+      "sass": "./src/index.scss"
+    }
+  }
+}

package/src/application.js

@@ -0,0 +1,11 @@
+import { initAll } from 'nhsuk-frontend'
+
+import { SearchElement } from './components/search/search.js'
+
+// Initiate custom elements
+customElements.define('app-search', SearchElement)
+
+// Initiate scripts on page load
+document.addEventListener('DOMContentLoaded', () => {
+  initAll()
+})

package/src/application.scss

@@ -0,0 +1,2 @@
+// NHS.UK Eleventy Plugin components
+@forward "pkg:@x-govuk/nhsuk-eleventy-plugin";

package/src/components/_index.scss

@@ -0,0 +1,12 @@
+@forward "attribution";
+@forward "blockquote";
+@forward "code";
+@forward "contents-list";
+@forward "footnotes-list";
+@forward "hero";
+@forward "image";
+@forward "metadata";
+@forward "prose-scope";
+@forward "related";
+@forward "search";
+@forward "sub-navigation";

package/src/components/attribution/_index.scss

@@ -0,0 +1,13 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/attribution") {
+  .app-attribution {
+    margin: 0 0 nhsuk-spacing(4);
+  }
+
+  .app-attribution__caption {
+    color: $nhsuk-secondary-text-colour;
+    margin: nhsuk-spacing(-2) 0 nhsuk-spacing(6);
+    padding: 0 0 0 nhsuk-spacing(6);
+  }
+}

package/src/components/blockquote/_index.scss

@@ -0,0 +1,22 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/blockquote") {
+  .app-blockquote {
+    margin: 0 0 nhsuk-spacing(4);
+    padding: 0 0 0 nhsuk-spacing(6);
+
+    p {
+      position: relative;
+
+      &::before {
+        content: "\201C";
+        position: absolute;
+        right: 100%;
+      }
+
+      &:last-of-type::after {
+        content: "\201D";
+      }
+    }
+  }
+}

package/src/components/card-group/macro.njk

@@ -0,0 +1,3 @@
+{% macro appCardGroup(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/components/card-group/template.njk

@@ -0,0 +1,26 @@
+{% from "nhsuk/components/card/macro.njk" import card as nhsukCard %}
+
+{% if params.columns == 2 %}{% set grid = "one-half" %}
+{% elif params.columns == 3 %}{% set grid = "one-third" %}
+{% elif params.columns == 4 %}{% set grid = "one-quarter" %}
+{% else %}{% set grid = "full" %}{% endif %}
+
+<ul class="nhsuk-grid-row nhsuk-card-group">
+{% set items = getData(params.items) | itemsFromCollection(params.limit) %}
+{% for item in items %}
+  <li class="nhsuk-grid-column-{{ grid }} nhsuk-card-group__item">
+    {{ nhsukCard({
+      clickable: item.href and params.clickable,
+      primary: params.type == "primary",
+      secondary: params.type == "secondary",
+      heading: item.heading,
+      headingClasses: "nhsuk-u-font-size-22" if params.title else "nhsuk-u-font-size-26" + (" nhsuk-u-margin-bottom-2" if item.descriptionHtml else ""),
+      headingLevel: 3 if params.title else 2,
+      href: item.href,
+      descriptionHtml: item.descriptionHtml,
+      imgALT: item.imgALT,
+      imgURL: item.imgURL
+    }) | indent(4) }}
+  </li>
+{% endfor %}
+</ul>

package/src/components/code/_index.scss

@@ -0,0 +1,153 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+// Use same colour for inline code as that used on NHS.UK Digital service manual.
+// https://github.com/nhsuk/nhsuk-service-manual/blob/main/app/stylesheets/app/_code-highlight.scss
+$_code-colour: #dd1144;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/code") {
+  .app-code--inline,
+  .app-code--block {
+    font-family: ui-monospace, monospace;
+    -webkit-font-smoothing: auto;
+  }
+
+  .app-code--inline {
+    background-color: nhsuk-colour("white");
+    color: $_code-colour;
+    font-size: 0.875em;
+    padding: 2px nhsuk-spacing(1);
+
+    a & {
+      color: inherit;
+    }
+
+    // Ensure links within inline code blocks receive focus colour
+    a:focus & {
+      background: $nhsuk-focus-colour;
+    }
+  }
+
+  .app-code--block {
+    background-color: nhsuk-colour("white");
+    overflow: auto;
+    padding: nhsuk-spacing(4);
+    scrollbar-color: nhsuk-colour("grey-1") $nhsuk-border-colour;
+    scrollbar-width: thin;
+
+    @include nhsuk-font(16, $line-height: 1.4);
+    @include nhsuk-responsive-margin(4, "bottom");
+
+    + .nhsuk-heading-l {
+      padding-top: nhsuk-spacing(4);
+    }
+
+    + .nhsuk-heading-m,
+    + .nhsuk-heading-s {
+      padding-top: nhsuk-spacing(2);
+    }
+
+    &:focus {
+      box-shadow: 0 0 0 #{$nhsuk-focus-width * 2} $nhsuk-focus-colour;
+      outline: $nhsuk-focus-width solid nhsuk-colour("black");
+    }
+  }
+
+  // Reverse the colour of code that uses shell highlighting
+  .app-code__language--shell {
+    background-color: nhsuk-colour("black");
+    border: $nhsuk-focus-width solid nhsuk-colour("white");
+    -webkit-font-smoothing: auto;
+    margin-left: $nhsuk-focus-width * -1;
+    margin-right: $nhsuk-focus-width * -1;
+
+    code {
+      filter: invert(100%);
+    }
+  }
+
+  .app-code__comment,
+  .app-code__quote {
+    color: nhsuk-tint(nhsuk-colour("grey-1"), 30);
+    font-style: italic;
+  }
+
+  .app-code__keyword,
+  .app-code__selector-tag,
+  .app-code__subst {
+    color: nhsuk-colour("black");
+    font-weight: bold;
+  }
+
+  .app-code__number,
+  .app-code__literal,
+  .app-code__variable,
+  .app-code__template-variable,
+  .app-code__tag .app-code__attr {
+    color: nhsuk-colour("green");
+  }
+
+  .app-code__string,
+  .app-code__doctag {
+    color: nhsuk-colour("red");
+  }
+
+  .app-code__title,
+  .app-code__section,
+  .app-code__selector-id {
+    color: nhsuk-colour("purple");
+    font-weight: bold;
+  }
+
+  .app-code__subst {
+    font-weight: normal;
+  }
+
+  .app-code__type,
+  .app-code__class .app-code__title {
+    color: nhsuk-colour("dark-pink");
+    font-weight: bold;
+  }
+
+  .app-code__tag,
+  .app-code__name,
+  .app-code__attribute {
+    color: $nhsuk-link-active-colour;
+    font-weight: normal;
+  }
+
+  .app-code__regexp,
+  .app-code__link {
+    color: nhsuk-colour("green");
+  }
+
+  .app-code__symbol,
+  .app-code__bullet {
+    color: nhsuk-colour("purple");
+  }
+
+  .app-code__builtin,
+  .app-code__builtin-name {
+    color: nhsuk-colour("blue");
+  }
+
+  .app-code__meta {
+    color: nhsuk-colour("grey-1");
+    font-weight: bold;
+  }
+
+  .app-code__deletion {
+    background: nhsuk-tint(nhsuk-colour("red"), 80);
+  }
+
+  .app-code__addition {
+    background: nhsuk-tint(nhsuk-colour("green"), 80);
+  }
+
+  .app-code__emphasis {
+    font-style: italic;
+  }
+
+  .app-code__strong {
+    font-weight: bold;
+  }
+}

package/src/components/contents-list/_index.scss

@@ -0,0 +1,18 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/contents-list") {
+  .nhsuk-contents-list ol {
+    // stylelint-disable-next-line scss/at-extend-no-missing-placeholder
+    @extend .nhsuk-contents-list__list;
+  }
+
+  .nhsuk-contents-list li {
+    // stylelint-disable-next-line scss/at-extend-no-missing-placeholder
+    @extend .nhsuk-contents-list__item;
+  }
+
+  .nhsuk-contents-list a {
+    // stylelint-disable-next-line scss/at-extend-no-missing-placeholder
+    @extend .nhsuk-contents-list__link;
+  }
+}

package/src/components/document-header/macro.njk

@@ -0,0 +1,3 @@
+{% macro appDocumentHeader(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/components/document-header/template.njk

@@ -0,0 +1,10 @@
+{% from "components/heading/macro.njk" import appHeading %}
+
+<header class="nhsuk-u-reading-width">
+  {{ appHeading({
+    caption: params.caption,
+    title: params.title,
+    description: params.description
+  }) | indent(2) }}
+</header>
+

package/src/components/document-list/macro.njk

@@ -0,0 +1,3 @@
+{% macro appDocumentList(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/components/document-list/template.njk

@@ -0,0 +1,22 @@
+{% from "nhsuk/components/card/macro.njk" import card as nhsukCard %}
+
+<div class="nhsuk-u-reading-width">
+{% if params.items.length > 0 %}
+  <ol class="nhsuk-grid-row nhsuk-card-group{%- if params.classes %} {{ params.classes }}{% endif %}">
+  {% for item in params.items | itemsFromCollection %}
+    <li class="nhsuk-grid-column-full nhsuk-card-group__item">
+      {{ nhsukCard({
+        secondary: true,
+        heading: item.heading,
+        headingClasses: params.headingClasses or "nhsuk-u-font-size-22" + (" nhsuk-u-margin-bottom-2" if item.descriptionHtml else ""),
+        headingLevel: params.headingLevel or 2,
+        href: item.href,
+        descriptionHtml: item.descriptionHtml
+      }) | indent(6) }}
+    </li>
+  {% endfor %}
+  </ol>
+{% else %}
+  <p class="nhsuk-body">No documents found.</p>
+{% endif %}
+</div>

package/src/components/footnotes-list/_index.scss

@@ -0,0 +1,55 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/footnotes-list") {
+  // Link to footnote
+  a[aria-describedby="footnotes-label"] {
+    @include nhsuk-font(16);
+    @include nhsuk-link-style-no-visited-state;
+  }
+
+  a[aria-describedby="footnotes-label"]::before {
+    color: currentcolor;
+    content: "[";
+  }
+
+  a[aria-describedby="footnotes-label"]::after {
+    color: currentcolor;
+    content: "]";
+  }
+
+  // Footnotes
+  .app-footnotes-list {
+    counter-reset: footnotes;
+    list-style-type: none;
+    padding-left: 0;
+
+    li {
+      counter-increment: footnotes;
+      padding: nhsuk-spacing(3);
+      padding-left: nhsuk-spacing(8);
+      position: relative;
+    }
+
+    li::before {
+      content: counter(footnotes) ".";
+      left: nhsuk-spacing(4);
+      position: absolute;
+    }
+
+    a[aria-label="Back to content"] {
+      position: relative;
+      text-underline-offset: 0;
+      top: 2px;
+
+      @include nhsuk-link-style-no-visited-state;
+    }
+
+    :target {
+      background-color: nhsuk-tint($nhsuk-focus-colour, 75%);
+    }
+
+    :last-child {
+      margin-bottom: 0;
+    }
+  }
+}

package/src/components/heading/macro.njk

@@ -0,0 +1,3 @@
+{% macro appHeading(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/components/heading/template.njk

@@ -0,0 +1,15 @@
+{% set level = params.level or 1 %}
+{% set size = params.size or "xl" %}
+{% if params.caption %}
+<span class="nhsuk-caption-{{ size }}">
+  {{- params.caption -}}
+</span>
+{% endif %}
+<h{{level}} class="nhsuk-heading-{{ size }}{%- if params.classes %} {{ params.classes }}{% endif %}">
+  {{- params.title | safe -}}
+</h{{level}}>
+{% if params.description -%}
+<p class="{{ "nhsuk-lede-text" if level == 1 else "nhsuk-body nhsuk-u-reading-width" }}">
+  {{- params.description | markdown("inline") | noOrphans | safe -}}
+</p>
+{% endif %}

package/src/components/hero/_index.scss

@@ -0,0 +1,17 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/hero") {
+  .app-hero__caption {
+    color: $nhsuk-reverse-text-colour;
+  }
+
+  .app-hero__image {
+    max-width: 100%;
+
+    @include nhsuk-responsive-padding(8, "top");
+
+    @include nhsuk-media-query($until: desktop) {
+      display: none;
+    }
+  }
+}

package/src/components/hero/macro.njk

@@ -0,0 +1,3 @@
+{% macro appHero(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/components/hero/template.njk

@@ -0,0 +1,36 @@
+{% from "nhsuk/components/button/macro.njk" import button as nhsukButton %}
+<div class="nhsuk-hero">
+  <div class="nhsuk-width-container nhsuk-hero--border">
+    <div class="nhsuk-grid-row">
+      <div class="nhsuk-grid-column-two-thirds">
+        <div class="nhsuk-hero__wrapper">
+          {% if params.caption %}
+          <span class="nhsuk-caption-xl app-hero__caption">
+            {{- params.caption -}}
+          </span>
+          {% endif %}
+          {% if params.title %}
+          <h1 class="nhsuk-hero__heading{%- if params.headingClasses %} {{ params.headingClasses }}{% endif %}">
+            {{- params.title | smart -}}
+          </h1>
+          {% endif %}
+          {% if params.description %}
+          <p class="nhsuk-body-l{% if not params.startButton %} nhsuk-u-margin-bottom-0{% endif %}">
+            {{- params.description | markdown("inline") | noOrphans -}}
+          </p>
+          {% endif %}
+          {{ nhsukButton({
+            classes: "nhsuk-button--reverse nhsuk-u-margin-0",
+            href: params.startButton.href,
+            text: params.startButton.text | default("Get started")
+          }) | indent(10) if params.startButton }}
+        </div>
+      </div>
+      {% if params.image %}
+      <div class="nhsuk-grid-column-one-third">
+        <img class="app-hero__image" src="{{ params.image.src }}" alt="{{ params.image.alt }}"{% if not params.image.alt %} role="presentation"{% endif %}>
+      </div>
+      {% endif %}
+    </div>
+  </div>
+</div>

package/src/components/image/_index.scss

@@ -0,0 +1,8 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/image") {
+  .app-image--full {
+    max-width: 100%;
+    width: 100%;
+  }
+}

package/src/components/metadata/_index.scss

@@ -0,0 +1,24 @@
+@use "../../vendor/nhsuk-frontend" as *;
+
+@include nhsuk-exports("nhsuk-eleventy-plugin/components/metadata") {
+  .app-metadata {
+    border-bottom: 1px solid $nhsuk-border-colour;
+    border-top: 1px solid $nhsuk-border-colour;
+    color: $nhsuk-secondary-text-colour;
+    margin-top: 0;
+
+    @include nhsuk-font($size: 16, $line-height: 1.5);
+    @include nhsuk-responsive-margin(7, "bottom");
+    @include nhsuk-responsive-padding(4, "bottom");
+    @include nhsuk-responsive-padding(4, "top");
+  }
+
+  .app-metadata__item {
+    display: flex;
+    gap: nhsuk-spacing(2) nhsuk-spacing(1);
+  }
+
+  .app-metadata__definition {
+    margin: 0;
+  }
+}

package/src/components/metadata/macro.njk

@@ -0,0 +1,3 @@
+{% macro appMetadata(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}