@defra/docusaurus-theme-govuk 0.0.7-alpha → 0.0.9-alpha

package/README.md

@@ -103,6 +103,13 @@ module.exports = {
           { text: 'GitHub', href: 'https://github.com/your-org/your-repo' },
         ],
       },
+
+      homepage: {
+        // Path to link the "Get started" button on the homepage masthead
+        getStartedHref: '/getting-started',
+        // Short description rendered below the heading
+        description: 'A short summary of what your service does.',
+      },
     },
   },
 };
@@ -110,6 +117,17 @@ module.exports = {
 
 ### Configuration Reference
 
+#### `themeConfig.govuk.homepage`
+
+Controls the homepage masthead — a full-width blue banner rendered between the service navigation and the page body on the homepage only. The banner shares the GOV.UK rebrand blue (`#1d70b8`) with the header and service navigation, so all three elements appear as one unified block.
+
+The masthead displays `siteConfig.tagline` as the heading and `homepage.description` as the lead paragraph. A GOV.UK "Start" button links to the configured `getStartedHref`.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `getStartedHref` | `string` | `'/getting-started'` | Path the "Get started" button links to |
+| `description` | `string` | — | Short description rendered below the heading |
+
 #### `themeConfig.govuk.header`
 
 | Property | Type | Description |
@@ -205,6 +223,62 @@ The sidebar is resolved once at build time and serialised into the site configur
 - The document must be in the `docs/` directory at the root of your Docusaurus site.
 - Heading IDs set via the `{#custom-id}` syntax are not yet respected — the generated anchor will use the slugified heading text.
 
+## Search
+
+The theme includes a built-in search bar rendered in the header. It uses [`@easyops-cn/docusaurus-search-local`](https://github.com/easyops-cn/docusaurus-search-local) to generate a local [lunr](https://lunrjs.com/) index at build time, and [alphagov's `accessible-autocomplete`](https://github.com/alphagov/accessible-autocomplete) as the accessible suggestion UI. No external service or API key is required.
+
+### Dependencies
+
+Install both packages in your Docusaurus site:
+
+```bash
+npm install @easyops-cn/docusaurus-search-local accessible-autocomplete
+```
+
+### Configuration
+
+The `@easyops-cn/docusaurus-search-local` theme must appear **before** `docusaurus-theme-govuk` in the `themes` array. This order ensures the search index is generated by the easyops plugin while the GOV.UK theme's `SearchBar` component wins the slot and controls the UI.
+
+```js
+themes: [
+  [
+    require.resolve('@easyops-cn/docusaurus-search-local'),
+    {
+      // Match your docs routeBasePath — '/' for docs-only mode
+      docsRouteBasePath: '/',
+      indexBlog: false,
+      indexPages: false,
+      // Hashed filenames allow long-term browser caching of the search index
+      hashed: 'filename',
+      highlightSearchTermsOnTargetPage: true,
+      searchResultContextMaxLength: 60,
+    },
+  ],
+  'docusaurus-theme-govuk',
+],
+```
+
+You must also add `docs.versionPersistence` to `themeConfig`. Without it, the `@easyops-cn/docusaurus-search-local` plugin throws a runtime error during static site generation (`Cannot read properties of undefined (reading 'versionPersistence')`):
+
+```js
+themeConfig: {
+  docs: {
+    versionPersistence: 'localStorage',
+  },
+  // ...
+},
+```
+
+### Search index coverage
+
+By default, all content under `docsRouteBasePath` is indexed. Blog and custom pages are excluded in the example above (`indexBlog: false`, `indexPages: false`). Adjust these to match your site structure.
+
+The search index is generated at build time. Run `npm run build` (or `docs:build`) before serving — the search bar will return no results in development mode (`docusaurus start`).
+
+### Result links
+
+The search bar deep-links directly to the matching heading within a page using anchor IDs derived from heading text, using the same slugifier as Docusaurus itself. Results show a breadcrumb context trail (`Page › Heading`) to help users identify where a match appears.
+
 ## 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:
@@ -225,4 +299,39 @@ Common components to override:
 
 - **Docusaurus**: ^3.0.0
 - **React**: ^18.0.0 || ^19.0.0
-- **Node.js**: 18+
+- **Node.js**: 18+
+
+## Open Source Attribution
+
+This theme includes a modified version of the [`@not-govuk/header`](https://github.com/daniel-ac-martin/NotGovUK/tree/master/packages/components/header) component from the [NotGovUK](https://github.com/daniel-ac-martin/NotGovUK) project.
+
+The modification adds a `children` prop so that additional content (the search bar) can be rendered as a flex sibling inside the header container. All other behaviour is unchanged.
+
+**Original licence:**
+
+```
+The MIT License (MIT)
+
+Copyright (C) 2019, 2020, 2021 Crown Copyright
+Copyright (C) 2019, 2020, 2021 Daniel A.C. Martin
+
+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.
+```
+
+The modified source is at [`src/theme/Header/index.js`](src/theme/Header/index.js).

package/index.js

@@ -215,6 +215,18 @@ module.exports = function themeGovuk(context, options) {
             // When installed from npm the theme ships no node_modules of its own,
             // so we must point webpack at the copy already present in the site.
             '@mdx-js/react': resolveFromSite('@mdx-js/react'),
+            // @not-govuk/header restricts subpath imports via its `exports` field.
+            // Our forked Header component imports logos and the SCSS by their dist paths.
+            // Alias them to absolute paths to bypass the exports field restriction.
+            ...((() => {
+              const headerDir = findPkgDir('@not-govuk/header', [siteDir, __dirname]);
+              return {
+                '@not-govuk/header/dist/CrownLogo$': path.join(headerDir, 'dist/CrownLogo.js'),
+                '@not-govuk/header/dist/CrownLogoOld$': path.join(headerDir, 'dist/CrownLogoOld.js'),
+                '@not-govuk/header/dist/CoatLogo$': path.join(headerDir, 'dist/CoatLogo.js'),
+                '@not-govuk/header/assets/Header.scss$': path.join(headerDir, 'assets/Header.scss'),
+              };
+            })()),
           },
         },
         plugins: [
@@ -275,7 +287,6 @@ module.exports = function themeGovuk(context, options) {
               );
             }
           ),
-          // 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,
@@ -294,6 +305,11 @@ module.exports = function themeGovuk(context, options) {
           rules: [
             {
               test: /\.m?js$/,
+              // `javascript/auto` lets webpack use its default JS pipeline (including
+              // Docusaurus's babel-loader rule) instead of treating every .mjs file
+              // as strict ESM. Without this, files like tslib.es6.mjs cause
+              // "Module parse failed: Unexpected token" because no loader is matched.
+              type: 'javascript/auto',
               resolve: {
                 fullySpecified: false,
               },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/docusaurus-theme-govuk",
-  "version": "0.0.7-alpha",
+  "version": "0.0.9-alpha",
   "description": "A Docusaurus theme implementing the GOV.UK Design System for consistent, accessible documentation sites",
   "main": "index.js",
   "license": "MIT",

package/src/css/components.scss

@@ -98,3 +98,195 @@
 .app-text-secondary {
   color: #505a5f;
 }
+
+// Ensure govuk-service-navigation--inverse styles apply in our rebranded context.
+// govuk-frontend compiles these inside @include _govuk-rebrand which may not
+// resolve correctly depending on SCSS load order — duplicate the rules explicitly.
+.govuk-template--rebranded .govuk-service-navigation--inverse {
+  background-color: #1d70b8;
+  border-bottom: none;
+  color: #fff;
+
+  .govuk-width-container {
+    border-width: 1px 0;
+    border-style: solid;
+    border-color: #8eb8dc;
+  }
+
+  .govuk-service-navigation__link {
+    color: #fff;
+
+    &:link,
+    &:visited {
+      color: #fff;
+    }
+
+    &:hover {
+      color: #fff;
+    }
+  }
+
+  .govuk-service-navigation__item,
+  .govuk-service-navigation__service-name {
+    border-color: #fff;
+  }
+}
+
+// Homepage masthead — a blue welcome band that appears between the service
+// navigation and the main content on the homepage only. The background matches
+// the GOV.UK rebrand header/service-navigation blue (#1d70b8 = $govuk-brand-colour)
+// so that all three elements read as one unified block.
+.app-masthead {
+  background-color: #1d70b8;
+  // Kill any top border that service-navigation might leave
+  border-top: none;
+}
+
+.app-masthead__container {
+  padding-top: 40px;    // govuk-spacing(7)
+}
+
+.app-masthead__title {
+  color: #fff;
+
+  // Override the default dark govuk heading colour
+  &.govuk-heading-xl {
+    color: #fff;
+    margin-bottom: 0;
+  }
+}
+
+.app-masthead__description {
+  color: #fff;
+  font-size: 1.5rem;
+  line-height: 1.25;
+}
+
+// Search bar rendered as a flex sibling inside govuk-header__container.
+// govuk-frontend's container uses a clearfix float layout; we switch it to
+// flex so children line up in a row and can be vertically centred.
+// margin-left:auto on .app-header-search pushes it to the right edge.
+.govuk-header__container {
+  display: flex;
+  align-items: center;
+  flex-wrap: nowrap;
+}
+
+.app-header-search {
+  margin-left: auto;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  z-index: 1;
+
+  // accessible-autocomplete wrapper
+  .autocomplete__wrapper {
+    position: relative;
+    width: 300px;
+  }
+
+  // Input field — always white background with search icon on the left
+  .autocomplete__input {
+    width: 100%;
+    padding: 4px 8px 4px 40px;
+    border: 2px solid #fff;
+    border-radius: 0;
+    background-color: #fff;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%230b0c0c' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: 10px center;
+    background-size: 20px 20px;
+    color: #0b0c0c;
+    font-family: Helvetica, Arial, sans-serif;
+    font-size: 0.875rem;
+    box-sizing: border-box;
+
+    &::placeholder {
+      color: #505a5f;
+    }
+
+    &:focus {
+      outline: 3px solid #fd0;
+      outline-offset: 0;
+    }
+  }
+
+  // Dropdown menu
+  .autocomplete__menu {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    background: #fff;
+    border: 2px solid #0b0c0c;
+    border-radius: 0;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    max-height: 342px;
+    overflow-y: auto;
+    z-index: 10;
+  }
+
+  // Inline menu variant (not used, but scoped just in case)
+  .autocomplete__menu--inline {
+    position: relative;
+  }
+
+  .autocomplete__option {
+    padding: 8px 12px;
+    font-family: Helvetica, Arial, sans-serif;
+    font-size: 0.875rem;
+    color: #0b0c0c;
+    cursor: pointer;
+    border-bottom: 1px solid #f3f2f1;
+
+    &:last-child {
+      border-bottom: none;
+    }
+  }
+
+  .autocomplete__option--focused,
+  .autocomplete__option:hover {
+    background: #1d70b8;
+    color: #fff;
+    outline: none;
+
+    .app-search__context {
+      color: rgba(255, 255, 255, 0.8);
+    }
+  }
+
+  // Two-line suggestion layout
+  .app-search__title {
+    display: block;
+  }
+
+  .app-search__context {
+    display: block;
+    font-size: 0.75rem;
+    color: #505a5f;
+    margin-top: 2px;
+  }
+
+  .autocomplete__option--no-results {
+    padding: 8px 12px;
+    font-family: Helvetica, Arial, sans-serif;
+    font-size: 0.875rem;
+    color: #505a5f;
+  }
+
+  // Status / hint text (visually hidden assistive text)
+  .autocomplete__status {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+}
+

package/src/theme/DocItem/Content/index.js

@@ -1,15 +1,23 @@
 import React from 'react';
 import {useDoc} from '../docContext';
 import MDXContent from '@theme/MDXContent';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 // Render a synthetic title if needed
 function useSyntheticTitle() {
   const {metadata, frontMatter, contentTitle} = useDoc();
+  const {siteConfig} = useDocusaurusContext();
   const shouldRender =
-    !frontMatter.hide_title && typeof contentTitle === 'undefined';
+    !frontMatter.hide_title &&
+    typeof contentTitle === 'undefined' &&
+    metadata.slug !== '/';
   if (!shouldRender) {
     return null;
   }
+  // For the root index page, use the Docusaurus site title instead of the filename
+  if (metadata.title?.toLowerCase() === 'index') {
+    return siteConfig.title;
+  }
   return metadata.title;
 }
 

package/src/theme/DocItem/Metadata/index.js

@@ -1,10 +1,16 @@
 import React from 'react';
 import Head from '@docusaurus/Head';
 import {useDoc} from '../docContext';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 export default function DocItemMetadata() {
   const {metadata} = useDoc();
-  const {title, description} = metadata;
+  const {siteConfig} = useDocusaurusContext();
+  const {description} = metadata;
+  // Use the Docusaurus site title for root index pages instead of the filename
+  const title = metadata.title?.toLowerCase() === 'index'
+    ? siteConfig.title
+    : metadata.title;
 
   return (
     <Head>

package/src/theme/Header/index.js

@@ -0,0 +1,170 @@
+/**
+ * Forked from @not-govuk/header (MIT Licence)
+ * Copyright (C) 2019–2021 Crown Copyright
+ * Copyright (C) 2019–2021 Daniel A.C. Martin
+ *
+ * Modifications: added `children` prop rendered as a flex sibling inside the
+ * header container, allowing content (e.g. a search bar) to be injected into
+ * the right-hand side of `govuk-header__container`.
+ */
+
+import React from 'react';
+import {classBuilder} from '@react-foundry/component-helpers';
+import {Link} from '@not-govuk/link';
+import {WidthContainer} from '@not-govuk/width-container';
+import {CrownLogo} from '@not-govuk/header/dist/CrownLogo';
+import {CrownLogoOld} from '@not-govuk/header/dist/CrownLogoOld';
+import {CoatLogo} from '@not-govuk/header/dist/CoatLogo';
+import '@not-govuk/header/assets/Header.scss';
+
+const departmentMap = {
+  'home-office': 'Home Office',
+  'department-for-communities-and-local-government': 'DCLG',
+  'department-for-culture-media-sport': 'DCMS',
+  'department-for-environment-food-rural-affairs': 'DEFRA',
+  'department-for-work-pensions': 'DWP',
+  'foreign-commonwealth-development-office': 'FCDO',
+  'foreign-commonwealth-office': 'FCO',
+  'hm-revenue-customs': 'HMRC',
+  'hm-treasury': 'HM Treasury',
+  'ministry-of-justice': 'MoJ',
+  'office-of-the-leader-of-the-house-of-lords': '',
+  'scotland-office': 'Scotland Office',
+  'wales-office': 'Wales Office',
+};
+
+const departmentText = (d) => {
+  if (!d) return null;
+  return (
+    departmentMap[d] ||
+    d
+      .split('-')
+      .map((e) => {
+        switch (e) {
+          case 'and': return '';
+          case 'hm':  return 'HM';
+          case 'for': return '';
+          case 'of':  return 'o';
+          case 'the': return '';
+          default:    return e.charAt(0).toUpperCase();
+        }
+      })
+      .join('')
+  );
+};
+
+const Header = ({
+  children,
+  classBlock,
+  classModifiers: _classModifiers = [],
+  className,
+  department,
+  govUK = false,
+  maxContentsWidth,
+  navigation = [],
+  organisationHref,
+  organisationText,
+  rebrand = false,
+  serviceHref = '/',
+  serviceName,
+  signOutHref,
+  signOutText = 'Sign out',
+  logo: _logo,
+  ...attrs
+}) => {
+  const classModifiers = Array.isArray(_classModifiers)
+    ? _classModifiers
+    : [_classModifiers];
+
+  const classes = classBuilder(
+    'govuk-header',
+    classBlock,
+    [...classModifiers, department],
+    className,
+  );
+
+  const A = (props) => (
+    <Link classBlock={classes('link')} {...props} />
+  );
+
+  const orgHref = organisationHref || (govUK ? 'https://www.gov.uk/' : '/');
+  const orgText =
+    organisationText || (govUK ? 'GOV.UK' : departmentText(department));
+
+  const navLinks = !signOutHref
+    ? navigation
+    : [...navigation, {href: signOutHref, text: signOutText, forceExternal: true}];
+
+  const logo =
+    _logo !== undefined
+      ? _logo
+      : govUK
+        ? rebrand
+          ? <CrownLogo focusable="false" className={classes('logotype')} height="30" width="162" />
+          : <CrownLogoOld focusable="false" className={classes('logotype')} height="30" width="148" />
+        : <CoatLogo aria-hidden="true" focusable="false" className={classes('logotype', ['coat'])} height="30" width="36" />;
+
+  return (
+    <header {...attrs} className={classes()} data-module="govuk-header">
+      <WidthContainer maxWidth={maxContentsWidth} className={classes('container')}>
+        <div className={classes('logo')}>
+          <A
+            href={orgHref}
+            classModifiers={[
+              'homepage',
+              orgText && orgText.length > 9 ? 'small' : undefined,
+            ]}
+          >
+            {logo}
+            {govUK ? null : (
+              <span className={classes('logotype-text')}>{orgText}</span>
+            )}
+          </A>
+        </div>
+
+        {(serviceName || navLinks.length) ? (
+          <div className={classes('content')}>
+            {serviceName && (
+              <A href={serviceHref} className={classes('service-name')}>
+                {serviceName}
+              </A>
+            )}
+            {navLinks.length ? (
+              <nav className={classes('navigation')} aria-label="Menu">
+                <button
+                  type="button"
+                  className={classes(
+                    'menu-button',
+                    undefined,
+                    'govuk-js-header-toggle',
+                  )}
+                  aria-controls="navigation"
+                  hidden
+                >
+                  Menu
+                </button>
+                <ul id="navigation" className={classes('navigation-list')}>
+                  {navLinks.map(({active, text, ...linkAttrs}, i) => (
+                    <li
+                      key={i}
+                      className={classes(
+                        'navigation-item',
+                        active ? 'active' : undefined,
+                      )}
+                    >
+                      <A {...linkAttrs}>{text}</A>
+                    </li>
+                  ))}
+                </ul>
+              </nav>
+            ) : null}
+          </div>
+        ) : null}
+
+        {children}
+      </WidthContainer>
+    </header>
+  );
+};
+
+export default Header;

package/src/theme/Homepage/index.js

@@ -1,47 +1,16 @@
 import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import useBaseUrl from '@docusaurus/useBaseUrl';
 import Layout from '@theme/Layout';
 
+// Homepage component for consumer sites that use a custom page (src/pages/index.js)
+// rather than a docs-based root. The masthead is rendered automatically by Layout
+// when the current path is '/' and themeConfig.govuk.homepage is configured.
 export default function Homepage() {
   const {siteConfig} = useDocusaurusContext();
-  const baseUrl = useBaseUrl('/');
 
   return (
     <Layout title={siteConfig.title} description={siteConfig.tagline}>
-      <div className="govuk-grid-row">
-        <div className="govuk-grid-column-two-thirds">
-          <h1 className="govuk-heading-xl govuk-!-margin-top-8">
-            {siteConfig.title}
-          </h1>
-
-          {siteConfig.tagline && (
-            <p className="govuk-body-l">
-              {siteConfig.tagline}
-            </p>
-          )}
-
-          <a
-            href={baseUrl}
-            role="button"
-            draggable="false"
-            className="govuk-button govuk-button--start govuk-!-margin-top-4"
-          >
-            Get started
-            <svg
-              className="govuk-button__start-icon"
-              xmlns="http://www.w3.org/2000/svg"
-              width="17.5"
-              height="19"
-              viewBox="0 0 33 40"
-              aria-hidden="true"
-              focusable="false"
-            >
-              <path fill="currentColor" d="M0 0h13l20 20-20 20H0l20-20z" />
-            </svg>
-          </a>
-        </div>
-      </div>
+      {/* Masthead is injected by Layout on the root path. This is because we need to adjust the styling for the header/nav, so it must live in the global Layout. */}
     </Layout>
   );
 }

package/src/theme/Layout/index.js

@@ -1,10 +1,13 @@
 import React from 'react';
 import '../../css/theme.scss';
-import {SkipLink, Header, Footer, PhaseBanner, ServiceNavigation} from '@not-govuk/simple-components';
+import {SkipLink, Footer, PhaseBanner, ServiceNavigation} from '@not-govuk/simple-components';
+import Header from '../Header';
 import SidebarNav from '../SidebarNav';
+import SearchBar from '@theme/SearchBar';
 import {useLocation} from '@docusaurus/router';
 import Head from '@docusaurus/Head';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 import LayoutProvider from '@theme/Layout/Provider';
 import AnnouncementBar from '@theme/AnnouncementBar';
 
@@ -110,9 +113,15 @@ export default function Layout(props) {
   const header = govukConfig.header || {};
   const phaseBanner = govukConfig.phaseBanner;
   const footer = govukConfig.footer || {};
+  const homepageConfig = govukConfig.homepage;
 
   // Strip baseUrl so sidebar matching works regardless of deployment path
   const pathname = stripBaseUrl(location.pathname, siteConfig.baseUrl);
+
+  const isHomepage = pathname === '/';
+  const getStartedHref = useBaseUrl(
+    homepageConfig?.getStartedHref || '/getting-started',
+  );
   const baseUrl = siteConfig.baseUrl.endsWith('/')
     ? siteConfig.baseUrl.slice(0, -1)
     : siteConfig.baseUrl;
@@ -169,14 +178,57 @@ export default function Layout(props) {
           rebrand
           organisationText={header.organisationText}
           organisationHref={header.organisationHref}
-        />
+        >
+          <div className="app-header-search">
+            <SearchBar />
+          </div>
+        </Header>
 
-        <ServiceNavigation 
+        <ServiceNavigation
           items={serviceNavItems}
           serviceName={header.serviceName}
           serviceHref={withBase(header.serviceHref || '/')}
+          classModifiers={isHomepage && homepageConfig ? 'inverse' : undefined}
         />
 
+        {isHomepage && homepageConfig && (
+          <div className="app-masthead">
+            <div className="govuk-width-container app-masthead__container">
+              <div className="govuk-grid-row">
+                <div className="govuk-grid-column-two-thirds">
+                  <h1 className="govuk-heading-xl app-masthead__title">
+                    {siteConfig.tagline || siteConfig.title}
+                  </h1>
+                  {homepageConfig.description && (
+                    <p className="app-masthead__description">
+                      {homepageConfig.description}
+                    </p>
+                  )}
+                  <a
+                    href={getStartedHref}
+                    role="button"
+                    draggable="false"
+                    className="govuk-button govuk-button--start govuk-button--inverse"
+                  >
+                    Get started
+                    <svg
+                      className="govuk-button__start-icon"
+                      xmlns="http://www.w3.org/2000/svg"
+                      width="17.5"
+                      height="19"
+                      viewBox="0 0 33 40"
+                      aria-hidden="true"
+                      focusable="false"
+                    >
+                      <path fill="currentColor" d="M0 0h13l20 20-20 20H0l20-20z" />
+                    </svg>
+                  </a>
+                </div>
+              </div>
+            </div>
+          </div>
+        )}
+
         <div className="govuk-width-container">
           {phaseBanner && (
             <PhaseBanner phase={phaseBanner.phase}>

package/src/theme/SearchBar/index.js

@@ -0,0 +1,206 @@
+import React, { useState, useCallback, useEffect, useMemo } from 'react';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import { useHistory } from '@docusaurus/router';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+// github-slugger is Docusaurus's own heading-anchor dependency.
+// Importing it directly ensures our anchor derivation never drifts from
+// the IDs Docusaurus writes into the built HTML.
+import GithubSlugger from 'github-slugger';
+// @generated module emitted by @easyops-cn/docusaurus-search-local at build time;
+// contains the hashed URL of the search index JSON (e.g. "search-index-fa7ba571.json").
+// eslint-disable-next-line import/no-unresolved
+import { searchIndexUrl } from '@generated/@easyops-cn/docusaurus-search-local/default/generated-constants.js';
+
+/**
+ * Resolve the template URL emitted by easyops.
+ * The URL contains a `{dir}` placeholder for the doc root / locale directory.
+ * For a single-locale site with docsRouteBasePath '/' the dir is empty.
+ */
+function resolveSearchIndexUrl(template) {
+  // Strip the {dir} token (single-locale / single-docs-plugin case).
+  return template.replace('{dir}', '');
+}
+
+/**
+ * Fetch the easyops-generated lunr document list.
+ *
+ * Document schema (all fields present depend on type):
+ *   b,i,t,u         — page root:   t = page title, b = breadcrumbs (empty)
+ *   h,i,p,t,u       — heading:     t = heading text, h = anchor hash, p = parent page id
+ *   i,p,s,t,u       — paragraph:   t = body text,   s = section heading / page title
+ *   h,i,p,s,t,u     — para+anchor: t = body text,   s = section heading, h = anchor hash
+ */
+async function fetchSearchDocs(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to load search index: ${res.status}`);
+  const data = await res.json();
+  return Object.values(data).flatMap((bucket) => bucket?.documents ?? []);
+}
+
+/** Minimal HTML escaping for values injected via innerHTML in suggestion templates. */
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function SearchBarInner() {
+  const history = useHistory();
+  const indexUrl = useBaseUrl(resolveSearchIndexUrl(searchIndexUrl));
+  const rootUrl   = useBaseUrl('');
+  const [docs, setDocs] = useState([]);
+
+  useEffect(() => {
+    fetchSearchDocs(indexUrl)
+      .then(setDocs)
+      .catch((err) => console.warn('[SearchBar] Could not load search index', err));
+  }, [indexUrl]);
+
+  // Build URL → page title lookup from page-root entries (those with `b` field).
+  const pageByUrl = useMemo(() => {
+    const map = new Map();
+    for (const doc of docs) {
+      if ('b' in doc) map.set(doc.u, doc.t);
+    }
+    return map;
+  }, [docs]);
+
+  // Derive the site root URL and its title directly from the index — the
+  // page-root entry with the shortest URL is always the site home page.
+  // This is more reliable than useBaseUrl('') which can return '' in some
+  // rendering contexts, causing the root title to leak into context trails.
+  const { rootPageUrl, rootPageTitle } = useMemo(() => {
+    let shortest = null;
+    for (const [url, title] of pageByUrl) {
+      if (shortest === null || url.length < shortest.url.length) {
+        shortest = { url, title };
+      }
+    }
+    return { rootPageUrl: shortest?.url ?? rootUrl, rootPageTitle: shortest?.title ?? null };
+  }, [pageByUrl, rootUrl]);
+
+  /**
+   * Walk the URL path upwards collecting ancestor page titles.
+   * Stops at (and excludes) the site root so the home-page title is never shown.
+   * e.g. "/interactive-map/api/button-definition"
+   *   → "/interactive-map/api" → "API reference"
+   *   → "/interactive-map"     → skipped (site root)
+   */
+  const getAncestorPages = useCallback(
+    (docUrl, currentPageTitle) => {
+      const ancestors = [];
+      const normalizedRoot = rootPageUrl.replace(/\/$/, '');
+      let url = docUrl.replace(/\/$/, '');
+      while (url.lastIndexOf('/') > 0) {
+        url = url.substring(0, url.lastIndexOf('/'));
+        if (url === normalizedRoot || url + '/' === rootPageUrl) break;
+        const title = pageByUrl.get(url) ?? pageByUrl.get(url + '/');
+        if (title && title !== currentPageTitle) {
+          ancestors.unshift(title);
+        }
+      }
+      return ancestors;
+    },
+    [pageByUrl, rootPageUrl],
+  );
+
+  const source = useCallback(
+    (query, populateResults) => {
+      if (!query || query.length < 2) {
+        populateResults([]);
+        return;
+      }
+      const q = query.toLowerCase();
+      // `s` = the heading/section label; `t` = body text (can be a full paragraph).
+      // Match against headings only so body paragraphs don't pollute results.
+      // Deduplicate by URL so each page appears at most once.
+      const seen = new Set();
+      const results = [];
+      for (const doc of docs) {
+        const label = doc.s ?? doc.t;
+        if (!label?.toLowerCase().includes(q)) continue;
+        if (seen.has(doc.u)) continue;
+        seen.add(doc.u);
+        const currentPage = pageByUrl.get(doc.u);
+        const ancestors   = getAncestorPages(doc.u, currentPage);
+        // Build a context trail: ancestor pages → current page.
+        // Exclude the result label itself and the site root title (home page
+        // title is uninformative — user already knows which site they're on).
+        const contextParts = [
+          ...ancestors,
+          ...(currentPage &&
+              currentPage !== label &&
+              currentPage !== rootPageTitle
+            ? [currentPage]
+            : []),
+        ];
+
+        // Derive the anchor using github-slugger — the same library Docusaurus
+        // uses when writing heading IDs into the built HTML, so they always match.
+        // Page-root entries (have `b`) live at the page URL with no hash.
+        // Heading/paragraph entries (have `h` field, even when empty) deep-link.
+        const anchor = ('h' in doc && !('b' in doc))
+          ? new GithubSlugger().slug(label)
+          : null;
+
+        results.push({
+          ...doc,
+          _label: label,
+          _context: contextParts.length ? contextParts.join(' › ') : null,
+          _url: anchor ? `${doc.u}#${anchor}` : doc.u,
+        });
+        if (results.length === 8) break;
+      }
+      populateResults(results);
+    },
+    [docs, pageByUrl, getAncestorPages, rootPageTitle],
+  );
+
+  const onConfirm = useCallback(
+    (selected) => {
+      if (selected?._url) {
+        history.push(selected._url);
+      }
+    },
+    [history],
+  );
+
+  const Autocomplete = require('accessible-autocomplete/react').default;
+
+  return (
+    <Autocomplete
+      id="govuk-search"
+      source={source}
+      templates={{
+        inputValue: (result) => (result ? result._label : ''),
+        suggestion: (result) => {
+          if (!result) return '';
+          const title = escapeHtml(result._label);
+          const context = result._context
+            ? `<span class="app-search__context">${escapeHtml(result._context)}</span>`
+            : '';
+          return `<span class="app-search__title">${title}</span>${context}`;
+        },
+      }}
+      displayMenu="overlay"
+      minLength={2}
+      placeholder="Search"
+      onConfirm={onConfirm}
+      tNoResults={() => 'No results found'}
+      tAssistiveHint={() =>
+        'When autocomplete results are available use up and down arrows to review and enter to select.'
+      }
+    />
+  );
+}
+
+/**
+ * SearchBar rendered inside the GOV.UK header.
+ * BrowserOnly ensures accessible-autocomplete (which uses DOM APIs) is never
+ * evaluated during server-side generation.
+ */
+export default function SearchBar() {
+  return <BrowserOnly>{() => <SearchBarInner />}</BrowserOnly>;
+}