@defra/docusaurus-theme-govuk 0.0.1-alpha

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crown Copyright (Defra)
+
+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,163 @@
+# docusaurus-theme-govuk
+
+A Docusaurus 3 theme that applies the [GOV.UK Design System](https://design-system.service.gov.uk/) to your documentation site.
+
+## Features
+
+- Full GOV.UK Design System shell: Header (with crown crest), Service Navigation, Phase Banner, Footer
+- GOV.UK typography applied to all Markdown/MDX content via prose scoping
+- Sidebar navigation driven by configuration (not Docusaurus's built-in sidebar UI)
+- Syntax-highlighted code blocks with copy button
+- Admonition blocks (:::note, :::warning, etc.) rendered as GOV.UK InsetText / WarningText
+- 404 page with GOV.UK styling
+- Bundled GDS Transport fonts and GOV.UK static assets
+- Compatible with React 18 and React 19
+
+## Installation
+
+```bash
+npm install docusaurus-theme-govuk
+```
+
+## Configuration
+
+Update your `docusaurus.config.js` (or `.cjs`):
+
+```js
+module.exports = {
+  title: 'My Service',
+  tagline: 'Service documentation',
+  url: 'https://example.gov.uk',
+  baseUrl: '/',
+
+  // Remove presets — the theme replaces preset-classic
+  presets: [],
+
+  // Register the GOV.UK theme
+  themes: ['docusaurus-theme-govuk'],
+
+  // Use plugin-content-docs directly for Markdown processing
+  plugins: [
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        routeBasePath: '/',
+        sidebarPath: require.resolve('./sidebars.js'),
+      },
+    ],
+  ],
+
+  // GOV.UK theme configuration
+  themeConfig: {
+    govuk: {
+      header: {
+        serviceName: 'My Service',
+        serviceHref: '/',
+      },
+
+      navigation: [
+        {
+          text: 'Documentation',
+          href: '/',
+          sidebar: [
+            { text: 'Introduction', href: '/' },
+            { text: 'Getting Started', href: '/getting-started' },
+            {
+              text: 'API Reference',
+              href: '/api',
+              items: [
+                { text: 'Methods', href: '/methods' },
+                { text: 'Events', href: '/events' },
+              ],
+            },
+          ],
+        },
+      ],
+
+      phaseBanner: {
+        phase: 'alpha',
+        text: 'This is a new service – your feedback will help us to improve it.',
+        feedbackHref: '/feedback',
+      },
+
+      footer: {
+        meta: [
+          { text: 'GitHub', href: 'https://github.com/your-org/your-repo' },
+        ],
+      },
+    },
+  },
+};
+```
+
+### Configuration Reference
+
+#### `themeConfig.govuk.header`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `serviceName` | `string` | Service name displayed in the GOV.UK header |
+| `serviceHref` | `string` | Link for the service name (default: `/`) |
+
+#### `themeConfig.govuk.navigation`
+
+Array of top-level navigation items. Each item appears in the Service Navigation bar.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `text` | `string` | Navigation link text |
+| `href` | `string` | Base path for this section |
+| `sidebar` | `array` | Optional sidebar items for this section |
+
+Each `sidebar` item:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `text` | `string` | Sidebar link text |
+| `href` | `string` | Path relative to the parent navigation `href` |
+| `items` | `array` | Optional nested sidebar items (one level of nesting) |
+
+#### `themeConfig.govuk.phaseBanner`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `phase` | `string` | Phase tag text (e.g. `'alpha'`, `'beta'`) |
+| `text` | `string` | Banner body text (plain text, rendered as React children) |
+| `feedbackHref` | `string` | Optional URL for a feedback link appended after the text |
+
+#### `themeConfig.govuk.footer`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `meta` | `array` | Array of `{ text, href }` objects rendered as footer meta links |
+
+## Sidebar Configuration
+
+The sidebar is configured through `themeConfig.govuk.navigation[].sidebar`, **not** through Docusaurus's built-in sidebar system. The Docusaurus `sidebars.js` file is still used by `plugin-content-docs` for route generation and doc ordering, but the visual sidebar is rendered by the GOV.UK theme.
+
+The sidebar supports up to 3 levels:
+1. **Level 1**: Service Navigation (top bar)
+2. **Level 2**: Sidebar items
+3. **Level 3**: Nested sidebar items (collapsible groups)
+
+## Overriding Components
+
+You can override any theme component by creating a file at the same path in your project's `src/theme/` directory. For example, to override the 404 page:
+
+```
+src/theme/NotFound/Content/index.js
+```
+
+Common components to override:
+- `Layout` — the full page shell
+- `NotFound/Content` — 404 page content
+- `Homepage` — the default landing page
+- `CodeBlock` — code block rendering
+- `Heading` — heading elements
+- `Admonition` — callout blocks
+
+## Compatibility
+
+- **Docusaurus**: ^3.0.0
+- **React**: ^18.0.0 || ^19.0.0
+- **Node.js**: 18+

package/index.js

@@ -0,0 +1,215 @@
+const path = require('path');
+const webpack = require('webpack');
+const CopyPlugin = require('copy-webpack-plugin');
+
+module.exports = function themeGovuk(context, options) {
+  const themePath = path.resolve(__dirname, './src/theme');
+  const shimPath = path.resolve(__dirname, './src/lib/react-foundry-router-shim.js');
+
+  // Resolve govuk-frontend assets directory from this package's dependencies
+  const govukFrontendAssetsPath = path.dirname(
+    require.resolve('govuk-frontend/package.json')
+  );
+
+  // The base URL for this Docusaurus site (e.g. '/interactive-map/')
+  const baseUrl = context.baseUrl || '/';
+
+  return {
+    name: 'docusaurus-theme-govuk',
+
+    getThemePath() {
+      return './src/theme';
+    },
+
+    getPathsToWatch() {
+      return [
+        path.join(themePath, '**/*.js'),
+        path.resolve(__dirname, './src/css/**/*.{scss,css}'),
+      ];
+    },
+
+    getClientModules() {
+      return [path.resolve(__dirname, './src/css/theme.scss')];
+    },
+
+    configureWebpack(config, isServer, utils) {
+      // Resolve React from the consumer (siteDir) to avoid dual-instance issues.
+      // The theme ships its own node_modules/react via `file:` linking,
+      // so we must force all React imports to the consumer's single copy.
+      const siteDir = context.siteDir;
+
+      // Helper: resolve a package from the consumer's siteDir.
+      // Uses require.resolve with paths so it follows Node's resolution
+      // (handles hoisted AND nested node_modules like @docusaurus/core/node_modules/react-router-dom).
+      function resolveFromSite(pkg) {
+        try {
+          return path.dirname(
+            require.resolve(`${pkg}/package.json`, { paths: [siteDir] })
+          );
+        } catch {
+          // Fallback: try resolving from @docusaurus/core (where react-router is nested in 3.9.x)
+          const docuCorePath = path.dirname(
+            require.resolve('@docusaurus/core/package.json', { paths: [siteDir] })
+          );
+          return path.dirname(
+            require.resolve(`${pkg}/package.json`, { paths: [docuCorePath] })
+          );
+        }
+      }
+
+      return {
+        resolve: {
+          extensions: ['.mjs', '.js', '.jsx', '.json', '.scss'],
+          fullySpecified: false,
+          alias: {
+            // Deduplicate React — always use the consumer's copy
+            'react': resolveFromSite('react'),
+            'react-dom': resolveFromSite('react-dom'),
+            'react/jsx-runtime': path.join(resolveFromSite('react'), 'jsx-runtime'),
+            'react/jsx-dev-runtime': path.join(resolveFromSite('react'), 'jsx-dev-runtime'),
+            // Deduplicate React Router — always use the consumer's copy
+            // (Docusaurus creates the Router context with its copy; we must read from the same copy)
+            'react-router': resolveFromSite('react-router'),
+            'react-router-dom': resolveFromSite('react-router-dom'),
+            'react-router-config': resolveFromSite('react-router-config'),
+            // Ensure @mdx-js/react resolves from the theme's node_modules,
+            // not the consumer's (which may not have it installed).
+            '@mdx-js/react': path.resolve(
+              __dirname,
+              'node_modules/@mdx-js/react'
+            ),
+          },
+        },
+        plugins: [
+          // Copy GOV.UK assets (fonts, images, manifest, rebrand) to the build
+          // output so they can be served statically. The SCSS outputs url()
+          // references via $govuk-assets-path pointing to /assets/; we must
+          // ensure the actual files exist at that path in the build.
+          new CopyPlugin({
+            patterns: [
+              {
+                from: path.join(govukFrontendAssetsPath, 'dist/govuk/assets'),
+                to: path.resolve(config.output.path || 'build', 'assets'),
+                noErrorOnMissing: true,
+              },
+            ],
+          }),
+          // Shim @react-foundry/router to bridge React Router v5 (Docusaurus) to v6 API
+          new webpack.NormalModuleReplacementPlugin(
+            /@react-foundry\/router/,
+            shimPath
+          ),
+          // Redirect @react-foundry packages to their CJS entry points.
+          // The .mjs entry points use extensionless re-exports (e.g. export * from './classes')
+          // which fail under webpack's fullySpecified enforcement for .mjs files.
+          new webpack.NormalModuleReplacementPlugin(
+            /^@react-foundry\/component-helpers$/,
+            require.resolve('@react-foundry/component-helpers')
+          ),
+          new webpack.NormalModuleReplacementPlugin(
+            /^@react-foundry\/client-component-helpers$/,
+            require.resolve('@react-foundry/client-component-helpers')
+          ),
+          new webpack.NormalModuleReplacementPlugin(
+            /^@react-foundry\/uri$/,
+            require.resolve('@react-foundry/uri')
+          ),
+          // Resolve asset paths from @not-govuk packages to govuk-frontend
+          new webpack.NormalModuleReplacementPlugin(
+            /^\.\.\/\.\.\/assets\/(images|fonts)\//,
+            (resource) => {
+              const assetType = resource.request.includes('/images/') ? 'images' : 'fonts';
+              const fileName = resource.request.split('/').pop();
+              resource.request = path.join(
+                govukFrontendAssetsPath,
+                `dist/govuk/assets/${assetType}/${fileName}`
+              );
+            }
+          ),
+          // Resolve govuk-frontend font paths from @not-govuk/page
+          new webpack.NormalModuleReplacementPlugin(
+            /^\.\.\/\.\.\/node_modules\/govuk-frontend\/dist\/govuk\/assets\/(fonts|images)\//,
+            (resource) => {
+              const assetType = resource.request.includes('/fonts/') ? 'fonts' : 'images';
+              const fileName = resource.request.split('/').pop();
+              resource.request = path.join(
+                govukFrontendAssetsPath,
+                `dist/govuk/assets/${assetType}/${fileName}`
+              );
+            }
+          ),
+          // Null out the font SCSS wrappers from @not-govuk/page.
+          // GovUKPage.scss imports gds-transport.css, and NotGovUKPage.scss
+          // imports roboto.css. These contain @font-face rules with relative
+          // URLs that, when inlined by sass and processed by css-loader,
+          // produce hashed font assets that are corrupt (OTS parsing errors).
+          // The SCSS pipeline (govuk-frontend _font-faces.scss) already
+          // provides working @font-face declarations for GDS Transport with
+          // the correct baseUrl-prefixed URLs, so these are redundant.
+          // Match both the relative request (../assets/X.scss) from JS files
+          // and any absolute-path form that webpack may resolve.
+          new webpack.NormalModuleReplacementPlugin(
+            /\/?(\.\.\/)?assets\/(GovUKPage|NotGovUKPage)\.scss$/,
+            path.resolve(__dirname, 'src/lib/empty-module.js')
+          ),
+        ],
+        module: {
+          rules: [
+            {
+              test: /\.m?js$/,
+              resolve: {
+                fullySpecified: false,
+              },
+            },
+            {
+              test: /\.scss$/,
+              use: [
+                'style-loader',
+                {
+                  loader: 'css-loader',
+                  options: {
+                    importLoaders: 2,
+                    url: {
+                      filter: (url) => {
+                        // Don't process absolute asset URLs — they are served as static files.
+                        // Matches both /assets/ and /<baseUrl>assets/ patterns.
+                        if (url.startsWith('/assets/') || url.startsWith(baseUrl + 'assets/')) {
+                          return false;
+                        }
+                        return true;
+                      },
+                    },
+                  },
+                },
+                'postcss-loader',
+                {
+                  loader: 'sass-loader',
+                  options: {
+                    implementation: require('sass'),
+                    // Override GOV.UK asset path to include the Docusaurus baseUrl.
+                    // The default '../../assets/' produces URLs without baseUrl,
+                    // causing 404s when baseUrl is not '/'.
+                    // Only prepend for SCSS/Sass files — plain CSS can't use Sass variables.
+                    additionalData: (content, loaderContext) => {
+                      if (/\.scss$|\.sass$/.test(loaderContext.resourcePath)) {
+                        return `$govuk-assets-path: '${baseUrl}assets/';\n` + content;
+                      }
+                      return content;
+                    },
+                    sassOptions: {
+                      includePaths: [
+                        path.resolve(__dirname, 'node_modules'),
+                      ],
+                      quietDeps: true,
+                      silenceDeprecations: ['import', 'if-function'],
+                    },
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      };
+    },
+  };
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@defra/docusaurus-theme-govuk",
+  "version": "0.0.1-alpha",
+  "description": "A Docusaurus theme implementing the GOV.UK Design System for consistent, accessible documentation sites",
+  "main": "index.js",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "src/"
+  ],
+  "keywords": [
+    "docusaurus",
+    "docusaurus-theme",
+    "govuk",
+    "gov.uk",
+    "design-system",
+    "documentation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DEFRA/docusaurus-theme-govuk"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@mdx-js/react": "^3.0.0",
+    "@not-govuk/simple-components": "^0.17.3",
+    "clsx": "^2.0.0",
+    "copy-webpack-plugin": "^11.0.0",
+    "css-loader": "^7.1.0",
+    "govuk-frontend": "^5.14.0",
+    "postcss-loader": "^8.2.0",
+    "prism-react-renderer": "^2.3.0",
+    "sass": "^1.97.0",
+    "sass-loader": "^16.0.0",
+    "style-loader": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

package/src/css/components.scss

@@ -0,0 +1,90 @@
+// Component styles extracted from inline JS styles
+// to allow consumer CSS overrides and reduce HTML payload.
+
+// Sidebar layout
+.app-layout-sidebar {
+  display: flex;
+  gap: 2rem;
+}
+
+.app-layout-sidebar__nav {
+  width: 250px;
+  flex-shrink: 0;
+}
+
+.app-layout-sidebar__content {
+  flex: 1;
+  min-width: 0;
+}
+
+// Code block
+.app-code-block {
+  position: relative;
+  margin-bottom: 1.25rem;
+}
+
+.app-code-block__title {
+  padding: 0.5rem 1rem;
+  background: #f3f2f1;
+  border-bottom: 1px solid #b1b4b6;
+  font-size: 0.875rem;
+  font-weight: 700;
+  font-family: 'GDS Transport', arial, sans-serif;
+}
+
+.app-code-block__pre {
+  padding: 1rem;
+  border-radius: 0;
+  overflow: auto;
+  font-size: 0.875rem;
+  line-height: 1.6;
+  font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  position: relative;
+  border: 1px solid #b1b4b6;
+  margin: 0;
+}
+
+.app-code-block__copy {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  padding: 0.25rem 0.75rem;
+  font-size: 0.8125rem;
+  border: 1px solid #b1b4b6;
+  border-radius: 0;
+  background: #f3f2f1;
+  cursor: pointer;
+  font-family: 'GDS Transport', arial, sans-serif;
+  color: #0b0c0c;
+
+  &:hover {
+    background: #dbdad9;
+  }
+}
+
+// Heading anchor link
+.app-heading-anchor {
+  margin-left: 0.5rem;
+  text-decoration: none;
+  opacity: 0.4;
+  font-size: 0.8em;
+
+  &:hover {
+    opacity: 1;
+  }
+}
+
+// Pagination
+.app-pagination__container {
+  display: flex;
+  justify-content: space-between;
+}
+
+.app-pagination__next {
+  text-align: right;
+}
+
+// Secondary text colour (matches govuk-frontend $govuk-secondary-text-colour)
+.app-text-secondary {
+  color: #505a5f;
+}

package/src/css/doc-overrides.css

@@ -0,0 +1,19 @@
+/* Hide Docusaurus breadcrumbs (defensive - in case classic elements leak through) */
+.theme-doc-breadcrumbs {
+  display: none !important;
+}
+
+/* Hide Docusaurus sidebar (we use GOV.UK NavigationMenu instead) */
+.theme-doc-sidebar-container {
+  display: none !important;
+}
+
+/* Make doc content full width */
+[class*='docMainContainer'] {
+  max-width: 100% !important;
+  flex: 1 !important;
+}
+
+.container {
+  max-width: 100%;
+}

package/src/css/prose-scope.scss

@@ -0,0 +1,59 @@
+// Import GOV.UK Frontend base (settings, tools, helpers) and core (placeholders)
+@import "govuk-frontend/dist/govuk/base";
+@import "govuk-frontend/dist/govuk/core";
+
+.app-prose-scope {
+  // Headings
+  h1 {
+    @extend %govuk-heading-xl;
+  }
+
+  h2 {
+    @extend %govuk-heading-l;
+  }
+
+  h3 {
+    @extend %govuk-heading-m;
+  }
+
+  h4 {
+    @extend %govuk-heading-s;
+  }
+
+  // Body text
+  p {
+    @extend %govuk-body-m;
+  }
+
+  // Bold text
+  strong,
+  b {
+    font-weight: 700;
+  }
+
+  // Lists
+  ul,
+  ol {
+    @extend %govuk-list;
+  }
+
+  ol {
+    @extend %govuk-list--number;
+  }
+
+  ul {
+    @extend %govuk-list--bullet;
+  }
+
+  // Links
+  a {
+    @extend %govuk-link;
+  }
+
+  // Section breaks
+  hr {
+    @extend %govuk-section-break;
+    @extend %govuk-section-break--visible;
+    @extend %govuk-section-break--xl;
+  }
+}

package/src/css/theme.scss

@@ -0,0 +1,18 @@
+/* Import doc overrides to hide Docusaurus built-in elements */
+@import './doc-overrides.css';
+
+/* Import prose scope for markdown content styling */
+@import './prose-scope.scss';
+
+/* Import component styles */
+@import './components.scss';
+
+/*
+ * Set the default font on the body so that ALL elements
+ * (header, footer, service-nav, etc.) inherit GDS Transport.
+ * The prose-scope only covers content inside .app-prose-scope;
+ * without this, outer chrome inherits the browser default serif.
+ */
+body {
+  font-family: 'GDS Transport', arial, sans-serif;
+}

package/src/lib/empty-module.js

@@ -0,0 +1,2 @@
+// Intentionally empty — used as a replacement for CSS modules that
+// produce corrupt font assets when processed by webpack's css-loader.