{"id":45631588,"url":"https://github.com/defra/docusaurus-theme-govuk","last_synced_at":"2026-03-01T21:01:17.432Z","repository":{"id":340214858,"uuid":"1165068288","full_name":"DEFRA/docusaurus-theme-govuk","owner":"DEFRA","description":"A GOV.UK Design System theme for Docusaurus","archived":false,"fork":false,"pushed_at":"2026-02-27T00:02:58.000Z","size":215,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T21:35:53.052Z","etag":null,"topics":["docusaurus","docusaurus-theme"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DEFRA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T19:42:38.000Z","updated_at":"2026-02-27T00:02:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"c121f8de-e1ba-4e7b-9983-91da0d85fb86","html_url":"https://github.com/DEFRA/docusaurus-theme-govuk","commit_stats":null,"previous_names":["defra/docusaurus-theme-govuk"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/DEFRA/docusaurus-theme-govuk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fdocusaurus-theme-govuk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fdocusaurus-theme-govuk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fdocusaurus-theme-govuk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fdocusaurus-theme-govuk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DEFRA","download_url":"https://codeload.github.com/DEFRA/docusaurus-theme-govuk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fdocusaurus-theme-govuk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29951023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T18:42:55.706Z","status":"ssl_error","status_checked_at":"2026-02-28T18:42:48.811Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docusaurus","docusaurus-theme"],"created_at":"2026-02-24T00:06:59.016Z","updated_at":"2026-03-01T21:01:17.427Z","avatar_url":"https://github.com/DEFRA.png","language":"JavaScript","readme":"# docusaurus-theme-govuk\n\nA Docusaurus 3 theme that applies the [GOV.UK Design System](https://design-system.service.gov.uk/) to your documentation site.\n\n## Features\n\n- Full GOV.UK Design System shell: Header (with crown crest), Service Navigation, Phase Banner, Footer\n- GOV.UK typography applied to all Markdown/MDX content via prose scoping\n- Sidebar navigation driven by configuration (not Docusaurus's built-in sidebar UI)\n- Syntax-highlighted code blocks with copy button\n- Admonition blocks (:::note, :::warning, etc.) rendered as GOV.UK InsetText / WarningText\n- 404 page with GOV.UK styling\n- GOV.UK static assets included (GDS Transport is **not** bundled — the theme uses Helvetica/Arial)\n- Compatible with React 18 and React 19\n\n\n## Installation\n\n```bash\nnpm install docusaurus-theme-govuk\n```\n\n### Consumer responsibilities\n\n- Install all required peer dependencies (see `peerDependencies` in the package).\n- Use the theme in your Docusaurus config as shown below.\n- Ensure your project uses compatible versions of Docusaurus and React.\n- Configure navigation and sidebar via `themeConfig.govuk.navigation`.\n\nNo additional setup is required beyond standard Docusaurus theme usage.\n\n## Configuration\n\nUpdate your `docusaurus.config.js` (or `.cjs`):\n\n```js\nmodule.exports = {\n  title: 'My Service',\n  tagline: 'Service documentation',\n  url: 'https://example.gov.uk',\n  baseUrl: '/',\n\n  // Remove presets — the theme replaces preset-classic\n  presets: [],\n\n  // Register the GOV.UK theme\n  themes: ['docusaurus-theme-govuk'],\n\n  // Use plugin-content-docs directly for Markdown processing\n  plugins: [\n    [\n      '@docusaurus/plugin-content-docs',\n      {\n        routeBasePath: '/',\n        sidebarPath: require.resolve('./sidebars.js'),\n      },\n    ],\n  ],\n\n  // GOV.UK theme configuration\n  themeConfig: {\n    govuk: {\n      header: {\n        serviceName: 'My Service',\n        serviceHref: '/',\n        organisationText: 'My Organisation',\n        organisationHref: 'https://example.gov.uk',\n      },\n\n      navigation: [\n        {\n          // Auto sidebar: headings from docs/index.md become sidebar items\n          text: 'Documentation',\n          href: '/',\n          sidebar: 'auto',\n        },\n        {\n          // Hardcoded sidebar: full control over labels, ordering, and nesting\n          text: 'API Reference',\n          href: '/api',\n          sidebar: [\n            { text: 'Introduction', href: '/api' },\n            {\n              text: 'Methods',\n              href: '/api/methods',\n              items: [\n                { text: 'Initialise', href: '/api/methods#initialise' },\n                { text: 'Destroy', href: '/api/methods#destroy' },\n              ],\n            },\n          ],\n        },\n      ],\n\n      phaseBanner: {\n        phase: 'alpha',\n        text: 'This is a new service – your feedback will help us to improve it.',\n        feedbackHref: '/feedback',\n      },\n\n      footer: {\n        meta: [\n          { text: 'GitHub', href: 'https://github.com/your-org/your-repo' },\n        ],\n      },\n\n      homepage: {\n        // Path to link the \"Get started\" button on the homepage masthead\n        getStartedHref: '/getting-started',\n        // Short description rendered below the heading\n        description: 'A short summary of what your service does.',\n      },\n    },\n  },\n};\n```\n\n### Configuration Reference\n\n#### `themeConfig.govuk.homepage`\n\nControls 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.\n\nThe masthead displays `siteConfig.tagline` as the heading and `homepage.description` as the lead paragraph. A GOV.UK \"Start\" button links to the configured `getStartedHref`.\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `getStartedHref` | `string` | `'/getting-started'` | Path the \"Get started\" button links to |\n| `description` | `string` | — | Short description rendered below the heading |\n\n#### `themeConfig.govuk.header`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `serviceName` | `string` | Service name displayed in the GOV.UK header |\n| `serviceHref` | `string` | Link for the service name (default: `/`) |\n| `organisationText` | `string` | Organisation name displayed in the header crown block |\n| `organisationHref` | `string` | URL the organisation name links to |\n\n#### `themeConfig.govuk.navigation`\n\nArray of top-level navigation items. Each item appears in the Service Navigation bar.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `text` | `string` | Navigation link text |\n| `href` | `string` | Base path for this section |\n| `sidebar` | `array \\| 'auto'` | Optional. Sidebar items for this section, or `'auto'` to generate from headings (see [Sidebar Configuration](#sidebar-configuration)) |\n\nWhen `sidebar` is an array, each item:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `text` | `string` | Sidebar link text |\n| `href` | `string` | Path for this item (absolute, e.g. `/api/methods`) |\n| `items` | `array` | Optional nested sidebar items (one level of nesting) |\n\n#### `themeConfig.govuk.phaseBanner`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `phase` | `string` | Phase tag text (e.g. `'alpha'`, `'beta'`) |\n| `text` | `string` | Banner body text (plain text, rendered as React children) |\n| `feedbackHref` | `string` | Optional URL for a feedback link appended after the text |\n\n#### `themeConfig.govuk.footer`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `meta` | `array` | Array of `{ text, href }` objects rendered as footer meta links |\n\n## Sidebar Configuration\n\nThe 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.\n\nThe sidebar supports up to 3 levels:\n1. **Level 1**: Service Navigation (top bar)\n2. **Level 2**: Sidebar items\n3. **Level 3**: Nested sidebar items (collapsible groups)\n\n### Hardcoded sidebar\n\nPass an array to `sidebar` to define the structure explicitly. This gives full control over labels, ordering, and anchor links:\n\n```js\nsidebar: [\n  { text: 'Overview', href: '/api' },\n  {\n    text: 'Constructor',\n    href: '/api#constructor',\n    items: [\n      { text: 'Options', href: '/api#options' },\n    ],\n  },\n]\n```\n\nNested groups are collapsible. A group is expanded when the current URL hash matches either the group's own `href` anchor or any child anchor.\n\n### Auto sidebar\n\nSet `sidebar: 'auto'` on a navigation section to generate the sidebar automatically from the section's corresponding Markdown document at build time:\n\n```js\n{\n  text: 'API Reference',\n  href: '/api',\n  sidebar: 'auto',\n}\n```\n\nThe theme reads `docs/\u003cslug\u003e.md` (or `.mdx`) where `\u003cslug\u003e` is derived from `href` (e.g. `href: '/api'` → `docs/api.md`). It parses the document's headings and builds the sidebar as follows:\n\n- `##` (h2) headings become top-level sidebar items\n- `###` (h3) headings become nested items under the preceding h2\n- Heading text is stripped of Markdown syntax (bold, italic, inline code, links) to produce plain-text labels\n\nThe sidebar is resolved once at build time and serialised into the site configuration. No runtime file reads occur.\n\n#### Limitations\n\n- Only h2 and h3 headings are included; h4 and deeper are ignored.\n- The document must be in the `docs/` directory at the root of your Docusaurus site.\n- Heading IDs set via the `{#custom-id}` syntax are not yet respected — the generated anchor will use the slugified heading text.\n\n## Search\n\nThe 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.\n\n### Dependencies\n\nInstall both packages in your Docusaurus site:\n\n```bash\nnpm install @easyops-cn/docusaurus-search-local accessible-autocomplete\n```\n\n### Configuration\n\nThe `@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.\n\n```js\nthemes: [\n  [\n    require.resolve('@easyops-cn/docusaurus-search-local'),\n    {\n      // Match your docs routeBasePath — '/' for docs-only mode\n      docsRouteBasePath: '/',\n      indexBlog: false,\n      indexPages: false,\n      // Hashed filenames allow long-term browser caching of the search index\n      hashed: 'filename',\n      highlightSearchTermsOnTargetPage: true,\n      searchResultContextMaxLength: 60,\n    },\n  ],\n  'docusaurus-theme-govuk',\n],\n```\n\nYou 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')`):\n\n```js\nthemeConfig: {\n  docs: {\n    versionPersistence: 'localStorage',\n  },\n  // ...\n},\n```\n\n### Search index coverage\n\nBy 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.\n\nThe 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`).\n\n### Result links\n\nThe 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.\n\n## Overriding Components\n\nYou 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:\n\n```\nsrc/theme/NotFound/Content/index.js\n```\n\nCommon components to override:\n- `Layout` — the full page shell\n- `NotFound/Content` — 404 page content\n- `Homepage` — the default landing page\n- `CodeBlock` — code block rendering\n- `Heading` — heading elements\n- `Admonition` — callout blocks\n\n## Compatibility\n\n- **Docusaurus**: ^3.0.0\n- **React**: ^18.0.0 || ^19.0.0\n- **Node.js**: 18+\n\n## Open Source Attribution\n\nThis 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.\n\nThe 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.\n\n**Original licence:**\n\n```\nThe MIT License (MIT)\n\nCopyright (C) 2019, 2020, 2021 Crown Copyright\nCopyright (C) 2019, 2020, 2021 Daniel A.C. Martin\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to use,\ncopy, modify, merge, publish, distribute, sublicense, and/or sell copies of the\nSoftware, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\nThe modified source is at [`src/theme/Header/index.js`](src/theme/Header/index.js).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Fdocusaurus-theme-govuk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefra%2Fdocusaurus-theme-govuk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Fdocusaurus-theme-govuk/lists"}