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

package/README.md

@@ -69,17 +69,23 @@ module.exports = {
 
       navigation: [
         {
+          // Auto sidebar: headings from docs/index.md become sidebar items
           text: 'Documentation',
           href: '/',
+          sidebar: 'auto',
+        },
+        {
+          // Hardcoded sidebar: full control over labels, ordering, and nesting
+          text: 'API Reference',
+          href: '/api',
           sidebar: [
-            { text: 'Introduction', href: '/' },
-            { text: 'Getting Started', href: '/getting-started' },
+            { text: 'Introduction', href: '/api' },
             {
-              text: 'API Reference',
-              href: '/api',
+              text: 'Methods',
+              href: '/api/methods',
               items: [
-                { text: 'Methods', href: '/methods' },
-                { text: 'Events', href: '/events' },
+                { text: 'Initialise', href: '/api/methods#initialise' },
+                { text: 'Destroy', href: '/api/methods#destroy' },
               ],
             },
           ],
@@ -121,14 +127,14 @@ Array of top-level navigation items. Each item appears in the Service Navigation
 |----------|------|-------------|
 | `text` | `string` | Navigation link text |
 | `href` | `string` | Base path for this section |
-| `sidebar` | `array` | Optional sidebar items for this section |
+| `sidebar` | `array \| 'auto'` | Optional. Sidebar items for this section, or `'auto'` to generate from headings (see [Sidebar Configuration](#sidebar-configuration)) |
 
-Each `sidebar` item:
+When `sidebar` is an array, each item:
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `text` | `string` | Sidebar link text |
-| `href` | `string` | Path relative to the parent navigation `href` |
+| `href` | `string` | Path for this item (absolute, e.g. `/api/methods`) |
 | `items` | `array` | Optional nested sidebar items (one level of nesting) |
 
 #### `themeConfig.govuk.phaseBanner`
@@ -154,6 +160,51 @@ The sidebar supports up to 3 levels:
 2. **Level 2**: Sidebar items
 3. **Level 3**: Nested sidebar items (collapsible groups)
 
+### Hardcoded sidebar
+
+Pass an array to `sidebar` to define the structure explicitly. This gives full control over labels, ordering, and anchor links:
+
+```js
+sidebar: [
+  { text: 'Overview', href: '/api' },
+  {
+    text: 'Constructor',
+    href: '/api#constructor',
+    items: [
+      { text: 'Options', href: '/api#options' },
+    ],
+  },
+]
+```
+
+Nested groups are collapsible. A group is expanded when the current URL hash matches either the group's own `href` anchor or any child anchor.
+
+### Auto sidebar
+
+Set `sidebar: 'auto'` on a navigation section to generate the sidebar automatically from the section's corresponding Markdown document at build time:
+
+```js
+{
+  text: 'API Reference',
+  href: '/api',
+  sidebar: 'auto',
+}
+```
+
+The theme reads `docs/<slug>.md` (or `.mdx`) where `<slug>` is derived from `href` (e.g. `href: '/api'` → `docs/api.md`). It parses the document's headings and builds the sidebar as follows:
+
+- `##` (h2) headings become top-level sidebar items
+- `###` (h3) headings become nested items under the preceding h2
+- Heading text is stripped of Markdown syntax (bold, italic, inline code, links) to produce plain-text labels
+
+The sidebar is resolved once at build time and serialised into the site configuration. No runtime file reads occur.
+
+#### Limitations
+
+- Only h2 and h3 headings are included; h4 and deeper are ignored.
+- 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.
+
 ## 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:

package/index.js

@@ -1,5 +1,57 @@
 const path = require('path');
 const fs = require('fs');
+// remove-markdown strips markdown syntax leaving plain text — used for sidebar labels.
+const removeMarkdown = require('remove-markdown');
+// github-slugger is what Docusaurus itself uses internally to generate heading
+// anchor IDs. Using the same library guarantees our sidebar hrefs match the
+// IDs emitted in the built HTML. A stateful GithubSlugger instance also
+// handles deduplication automatically (second "Options" → "options-1", etc.).
+const GithubSlugger = require('github-slugger');
+
+// Parse markdown content and build a sidebar config from h2/h3 headings.
+// h2 → top-level items; h3 → nested items under the preceding h2.
+// Items include both the display text and an anchor href (basePath + '#' + anchor).
+function parseHeadingsToSidebar(content, basePath) {
+  // Strip YAML front-matter only if the file genuinely starts with ---
+  // (do NOT use a greedy regex: api.md and other docs use --- as horizontal rules)
+  let stripped = content;
+  if (content.startsWith('---\n') || content.startsWith('---\r\n')) {
+    const closeIdx = content.indexOf('\n---', 3);
+    if (closeIdx !== -1) {
+      // Skip past the closing --- and any trailing newline
+      stripped = content.slice(closeIdx + 4).replace(/^\n/, '');
+    }
+  }
+  const lines = stripped.split('\n');
+
+  // One slugger instance per document — its internal counter provides the
+  // same -1, -2 deduplication that Docusaurus emits in the built HTML.
+  const slugger = new GithubSlugger();
+
+  const items = [];
+  let currentH2 = null;
+
+  for (const line of lines) {
+    const h2 = line.match(/^## (.+)$/);
+    const h3 = line.match(/^### (.+)$/);
+
+    if (h2) {
+      const raw = h2[1].trim();
+      const text = removeMarkdown(raw);
+      const anchor = slugger.slug(raw);
+      currentH2 = { text, href: `${basePath}#${anchor}`, _anchor: anchor };
+      items.push(currentH2);
+    } else if (h3 && currentH2) {
+      const raw = h3[1].trim();
+      const text = removeMarkdown(raw);
+      const anchor = slugger.slug(raw);
+      if (!currentH2.items) currentH2.items = [];
+      currentH2.items.push({ text, href: `${basePath}#${anchor}` });
+    }
+  }
+
+  return items.map(({ _anchor, ...item }) => item);
+}
 
 module.exports = function themeGovuk(context, options) {
   const siteDir = context.siteDir;
@@ -21,6 +73,41 @@ module.exports = function themeGovuk(context, options) {
   // The base URL for this Docusaurus site (e.g. '/interactive-map/')
   const baseUrl = context.baseUrl || '/';
 
+  // Pre-resolve sidebar: 'auto' entries in the navigation config by mutating
+  // the themeConfig object in-place. This runs synchronously before Docusaurus
+  // serialises siteConfig into the client bundle, so useDocusaurusContext()
+  // will already see the resolved sidebar arrays — no new client imports needed.
+  const govukNav = context.siteConfig.themeConfig?.govuk?.navigation;
+  if (Array.isArray(govukNav)) {
+    const docsDir = path.join(siteDir, 'docs');
+    for (const section of govukNav) {
+      if (section.sidebar !== 'auto') continue;
+      const href = section.href || '/';
+      const slug = href.replace(/^\//, '') || 'index';
+      let resolved = false;
+      for (const ext of ['.md', '.mdx']) {
+        const candidate = path.join(docsDir, `${slug}${ext}`);
+        if (fs.existsSync(candidate)) {
+          section.sidebar = {
+            _auto: true,
+            items: parseHeadingsToSidebar(
+              fs.readFileSync(candidate, 'utf-8'),
+              href
+            ),
+          };
+          resolved = true;
+          break;
+        }
+      }
+      if (!resolved) {
+        console.warn(
+          `[docusaurus-theme-govuk] sidebar: "auto" on "${href}" — could not find markdown file at ${path.join(docsDir, slug)}.(md|mdx)`
+        );
+        section.sidebar = { _auto: true, items: [] };
+      }
+    }
+  }
+
   return {
     name: 'docusaurus-theme-govuk',
 
@@ -108,6 +195,11 @@ module.exports = function themeGovuk(context, options) {
         resolve: {
           extensions: ['.mjs', '.js', '.jsx', '.json', '.scss'],
           fullySpecified: false,
+          // When the theme is consumed via a file: symlink, webpack resolves
+          // imports from the theme's real directory which has no node_modules.
+          // Adding the site's node_modules here ensures @docusaurus/* and any
+          // other peer dependency imports are found regardless of symlink depth.
+          modules: ['node_modules', path.resolve(siteDir, 'node_modules')],
           alias: {
             // Deduplicate React — always use the consumer's copy
             'react': resolveFromSite('react'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/docusaurus-theme-govuk",
-  "version": "0.0.5-alpha",
+  "version": "0.0.7-alpha",
   "description": "A Docusaurus theme implementing the GOV.UK Design System for consistent, accessible documentation sites",
   "main": "index.js",
   "license": "MIT",
@@ -32,9 +32,11 @@
     "clsx": "^2.0.0",
     "copy-webpack-plugin": "^11.0.0",
     "css-loader": "^7.1.0",
+    "github-slugger": "^2.0.0",
     "govuk-frontend": "^5.14.0",
     "postcss-loader": "^8.2.0",
     "prism-react-renderer": "^2.3.0",
+    "remove-markdown": "^0.6.3",
     "sass": "^1.97.0",
     "sass-loader": "^16.0.0",
     "style-loader": "^4.0.0"

package/src/css/components.scss

@@ -9,7 +9,17 @@
 
 .app-layout-sidebar__nav {
   width: 250px;
+  // Padding-left gives room for the nav's active indicator (margin-left: -14px)
+  // which would otherwise be clipped by the overflow-y containment.
+  padding-left: 15px;
   flex-shrink: 0;
+  position: sticky;
+  top: 1rem;
+  max-height: calc(100vh - 2rem);
+  overflow-y: auto;
+  // Always reserve the scrollbar gutter so expanding subnav items don't
+  // cause a horizontal layout shift when the scrollbar appears.
+  scrollbar-gutter: stable;
 }
 
 .app-layout-sidebar__content {

package/src/theme/Layout/index.js

@@ -1,6 +1,7 @@
 import React from 'react';
 import '../../css/theme.scss';
-import {SkipLink, Header, Footer, PhaseBanner, ServiceNavigation, NavigationMenu} from '@not-govuk/simple-components';
+import {SkipLink, Header, Footer, PhaseBanner, ServiceNavigation} from '@not-govuk/simple-components';
+import SidebarNav from '../SidebarNav';
 import {useLocation} from '@docusaurus/router';
 import Head from '@docusaurus/Head';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
@@ -37,6 +38,21 @@ function resolvePath(basePath, relativePath) {
   return `${cleanBase}/${relativePath}`;
 }
 
+// Return the effective sidebar descriptor for a navigation section.
+// Auto-generated sidebars are { _auto: true, items: [...] } (a plain object
+// that survives JSON serialisation, unlike array non-index properties).
+// Manual sidebars remain plain arrays and are wrapped here for uniform access.
+function getEffectiveSidebar(section) {
+  const s = section.sidebar;
+  if (s && typeof s === 'object' && !Array.isArray(s) && s._auto === true) {
+    return s; // { _auto: true, items: [...] }
+  }
+  if (Array.isArray(s)) {
+    return { _auto: false, items: s };
+  }
+  return null;
+}
+
 // Resolve all paths in sidebar items
 function resolveSidebarPaths(items, basePath) {
   return items.map(item => {
@@ -54,13 +70,21 @@ function resolveSidebarPaths(items, basePath) {
   });
 }
 
-// Find the active navigation section based on current path
+// Find the active navigation section based on current path.
 function getActiveSection(pathname, navigation) {
   return navigation.find(section => {
-    if (!section.sidebar) return false;
-    // Use the section's configured href as the base path
-    const basePath = section.href || '/';
-    const resolvedSidebar = resolveSidebarPaths(section.sidebar, basePath);
+    const sidebar = getEffectiveSidebar(section);
+    if (!sidebar) return false;
+    // First: check if current pathname matches the section's own base page or
+    // any sub-page. This handles auto-generated sidebars whose item hrefs
+    // include anchors (#...) and would never match a plain pathname.
+    const sectionPath = section.href || '/';
+    if (pathname === sectionPath || pathname.startsWith(sectionPath + '/')) {
+      return true;
+    }
+    // Fallback: match by exact item href (for array sidebars with sub-pages
+    // whose hrefs differ from the section's base href).
+    const resolvedSidebar = resolveSidebarPaths(sidebar.items, sectionPath);
     return resolvedSidebar.some(item => {
       if (pathname === item.href) return true;
       if (item.items) {
@@ -99,11 +123,16 @@ export default function Layout(props) {
     return `${baseUrl}${href.startsWith('/') ? href : `/${href}`}`;
   }
 
+  // Build-time auto-generated sidebars were resolved into the navigation
+  // array directly (sidebar: 'auto' replaced with sidebar: [...]) so we
+  // just read the array from siteConfig as normal.
+
   // Get active section for sidebar
   const activeSection = getActiveSection(pathname, navigation);
   const basePath = activeSection?.href || '/';
-  const sidebarItems = activeSection?.sidebar
-    ? resolveSidebarPaths(activeSection.sidebar, basePath).map(item => ({
+  const effectiveSidebar = activeSection ? getEffectiveSidebar(activeSection) : null;
+  const sidebarItems = effectiveSidebar
+    ? resolveSidebarPaths(effectiveSidebar.items, basePath).map(item => ({
         ...item,
         href: withBase(item.href),
         ...(item.items && {
@@ -164,7 +193,7 @@ export default function Layout(props) {
             {sidebarItems ? (
               <div className="app-layout-sidebar">
                 <aside className="app-layout-sidebar__nav">
-                  <NavigationMenu items={sidebarItems} />
+                  <SidebarNav items={sidebarItems} />
                 </aside>
                 <div className="app-layout-sidebar__content">
                   {children}

package/src/theme/SidebarNav/index.js

@@ -0,0 +1,102 @@
+import React, { useState, useEffect } from 'react';
+import { useLocation } from '@docusaurus/router';
+
+/**
+ * Hash- and pathname-aware sidebar navigation.
+ *
+ * Works for both anchor-based (auto-generated) and page-based (manual) sidebars.
+ *
+ * SSR / no-JS: all groups are rendered expanded so content is accessible.
+ * CSR after hydration:
+ *   - Anchor hrefs (e.g. /api#constructor): active when pathname AND hash both match
+ *   - Page hrefs (e.g. /building-a-plugin): active when pathname matches
+ *   - Groups expand when the group itself or any child is active
+ *
+ * State sentinel:
+ *   null = not yet hydrated → expand all groups (SSR safe)
+ *   str  = JS loaded (empty string means no hash present)
+ */
+export default function SidebarNav({ items }) {
+  const [hash, setHash] = useState(null);
+  const location = useLocation();
+
+  useEffect(() => {
+    const update = () => setHash(window.location.hash.slice(1));
+    update();
+    window.addEventListener('hashchange', update);
+    return () => window.removeEventListener('hashchange', update);
+  }, []);
+
+  // Split an href into its path and anchor components.
+  function parseHref(href) {
+    if (!href) return { path: '', anchor: '' };
+    const idx = href.indexOf('#');
+    if (idx === -1) return { path: href, anchor: '' };
+    return { path: href.slice(0, idx) || '/', anchor: href.slice(idx + 1) };
+  }
+
+  // Return true if the given href matches the current browser location.
+  //   Anchor hrefs: both pathname and hash must match.
+  //   Page hrefs:   pathname match is sufficient (exact or child path).
+  function isActive(href) {
+    const { path, anchor } = parseHref(href);
+    if (anchor) {
+      return location.pathname === path && hash === anchor;
+    }
+    return (
+      path !== '' &&
+      (location.pathname === path || location.pathname.startsWith(path + '/'))
+    );
+  }
+
+  const cls = 'not-govuk-navigation-menu';
+  const lCls = `${cls}__list`;
+
+  return (
+    <nav className={cls}>
+      <ul className={lCls}>
+        {items.map((item, i) => {
+          const hasChildren = Array.isArray(item.items) && item.items.length > 0;
+
+          // Pre-hydration (hash === null): expand everything so content is
+          // accessible without JS. After hydration: expand only if this group
+          // or one of its children is the active location.
+          const expanded =
+            hasChildren &&
+            (hash === null || isActive(item.href) || item.items.some(sub => isActive(sub.href)));
+
+          const active = hash !== null && isActive(item.href);
+
+          return (
+            <li
+              key={i}
+              className={`${lCls}__item${active ? ` ${lCls}__item--active` : ''}`}
+            >
+              <a href={item.href} className={`${lCls}__link`}>
+                {item.text}
+              </a>
+              {expanded && (
+                <ul className={`${lCls}__subitems`}>
+                  {item.items.map((sub, j) => {
+                    const subActive = hash !== null && isActive(sub.href);
+                    return (
+                      <li
+                        key={j}
+                        className={`${lCls}__item${subActive ? ` ${lCls}__item--active` : ''}`}
+                      >
+                        <a href={sub.href} className={`${lCls}__link`}>
+                          {sub.text}
+                        </a>
+                      </li>
+                    );
+                  })}
+                </ul>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}
+