sourcey 3.6.3 → 3.6.5

package/README.md

@@ -2,18 +2,14 @@
 
 > Docs straight from the source.
 
-Sourcey tells the whole product story. It turns specs, code, rich guides, changelog, roadmap pages, examples, and portable context files from your project into static HTML you can deploy anywhere.
+Sourcey turns OpenAPI, MCP, Doxygen XML, godoc, rustdoc, and Markdown into one static HTML site you own: reference, guides, changelog, roadmap, and llms.txt from the same build, deployable anywhere.
 
-No dashboard. No runtime. No API calls to render your own documentation.
+Everything renders at build time: no dashboard, no runtime, no API calls to render your own documentation.
 
 [![npm](https://img.shields.io/npm/v/sourcey)](https://www.npmjs.com/package/sourcey)
 [![build](https://img.shields.io/github/actions/workflow/status/sourcey/sourcey/ci.yml?branch=main)](https://github.com/sourcey/sourcey/actions)
 [![node](https://img.shields.io/node/v/sourcey)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/sourcey)](LICENSE)
-[![Go Reference](https://pkg.go.dev/badge/github.com/sourcey/sourcey/go/sourcey-godoc.svg)](https://pkg.go.dev/github.com/sourcey/sourcey/go/sourcey-godoc)
-[![Go Report Card](https://goreportcard.com/badge/github.com/sourcey/sourcey/go/sourcey-godoc)](https://goreportcard.com/report/github.com/sourcey/sourcey/go/sourcey-godoc)
-[![crates.io](https://img.shields.io/crates/v/sourcey.svg)](https://crates.io/crates/sourcey)
-[![docs.rs](https://docs.rs/sourcey/badge.svg)](https://docs.rs/sourcey)
 
 ```bash
 npx sourcey init
@@ -26,7 +22,7 @@ npx sourcey init
 ## Features
 
 - **OpenAPI 2.0, 3.0, 3.1, and 3.2**: full spec coverage including `QUERY` operations, response summaries, hierarchical tags, `deviceAuthorization` OAuth, `querystring` parameters, and `$self`-aware refs for multi-document APIs
-- **API reference from OpenAPI**: endpoints, parameters, request/response schemas, auto-generated code samples in 10 languages (cURL, JavaScript, TypeScript, Python, Go, Ruby, Java, PHP, Rust, C#)
+- **API reference from OpenAPI**: endpoints, parameters, request/response schemas, and auto-generated code samples across 10 supported languages. The default set is cURL, JavaScript, and Python; configure TypeScript, Go, Ruby, Java, PHP, Rust, and C# when you want them
 - **MCP server documentation**: tools, resources, prompts rendered as browsable reference with JSON-RPC, TypeScript, and Python code samples. Color-coded method types, annotation badges, connection config cards
 - **Rich guides**: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
 - **MkDocs source import**: point a tab at `mkdocs.yml`; Sourcey reads `docs_dir` and `nav` so existing MkDocs markdown sites can render without hand-copying the sidebar structure
@@ -60,6 +56,9 @@ Then `sourcey init` to scaffold a new project, or `sourcey build` against an exi
 
 ### Standalone Go docs generator
 
+[![Go Reference](https://pkg.go.dev/badge/github.com/sourcey/sourcey/go/sourcey-godoc.svg)](https://pkg.go.dev/github.com/sourcey/sourcey/go/sourcey-godoc)
+[![Go Report Card](https://goreportcard.com/badge/github.com/sourcey/sourcey/go/sourcey-godoc)](https://goreportcard.com/report/github.com/sourcey/sourcey/go/sourcey-godoc)
+
 For Go-only consumers without a JavaScript toolchain, `sourcey-godoc` ships as a separate native binary. It produces static Go docs sites or portable `godoc.json` snapshots.
 
 | Path     | Command                                                                                           |
@@ -68,17 +67,62 @@ For Go-only consumers without a JavaScript toolchain, `sourcey-godoc` ships as a
 | Homebrew | `brew install sourcey/tap/sourcey-godoc`                                                          |
 | Scoop    | `scoop bucket add sourcey https://github.com/sourcey/scoop-bucket && scoop install sourcey-godoc` |
 
+### Rust snapshot converter
+
+[![crates.io](https://img.shields.io/crates/v/sourcey.svg)](https://crates.io/crates/sourcey)
+[![docs.rs](https://docs.rs/sourcey/badge.svg)](https://docs.rs/sourcey)
+
+The `rustdoc()` adapter consumes nightly rustdoc JSON through the [`sourcey`](https://crates.io/crates/sourcey) companion crate and its `sourcey-rustdoc` converter, so CI can build Rust API docs from a committed snapshot on a stable toolchain. See [docs/adapters/rustdoc.md](docs/adapters/rustdoc.md).
+
 ## Quick start
 
 ```bash
-# From a single OpenAPI spec
-sourcey build api.yaml -o docs/
-
-# Multi-page site (reads sourcey.config.ts)
-sourcey build -o docs/
+# Scaffold a project (detects OpenAPI specs and Doxyfiles)
+npx sourcey init
 
 # Dev server with hot reload
 sourcey dev
+
+# Build static HTML to dist/
+sourcey build
+
+# Quick build from a single OpenAPI spec
+sourcey build api.yaml -o dist/
+```
+
+In CI, the [`sourcey/build-docs`](https://github.com/sourcey/build-docs) GitHub Action runs the build and deploys to GitHub Pages; see [deploying](https://sourcey.com/docs/deploying).
+
+### Astro integration
+
+Astro sites can mount Sourcey directly instead of running a separate docs CI job. The integration reads the same `sourcey.config.ts`, derives Sourcey's public `siteUrl` and `baseUrl` from Astro's `site`/`base` plus `routeBase`, serves docs in Astro dev, and writes docs into Astro's final build output.
+
+```typescript
+// astro.config.ts
+import { defineConfig } from "astro/config";
+import sourcey from "sourcey/astro";
+
+export default defineConfig({
+  site: "https://sourcey.com",
+  integrations: [
+    sourcey({
+      config: "./sourcey.config.ts",
+      routeBase: "/docs",
+    }),
+  ],
+});
+```
+
+You can also share an imported config object when you want one config module to feed both the CLI and Astro:
+
+```typescript
+import { defineConfig } from "astro/config";
+import sourcey from "sourcey/astro";
+import docs from "./sourcey.config";
+
+export default defineConfig({
+  site: "https://sourcey.com",
+  integrations: [sourcey({ config: docs, configDir: ".", routeBase: "/docs" })],
+});
 ```
 
 ## Configuration
@@ -168,8 +212,8 @@ cd sourcey && npm install
 npm run build && npm test
 cd go/sourcey-godoc && go test ./... && go vet ./...
 
-# Run the demo site
-cd demo && npx tsx ../src/cli.ts dev
+# Run the in-repo docs site against your working copy
+cd docs && npx tsx ../src/cli.ts dev
 ```
 
 ## License

package/dist/astro/index.d.ts

@@ -0,0 +1,89 @@
+import type { Plugin } from "vite";
+import type { PrettyUrls, ResolvedConfig, SourceyConfig } from "../config.js";
+export interface SourceyAstroOptions {
+    /**
+     * A path to `sourcey.config.ts`, a directory containing it, or an already
+     * imported Sourcey config object. Defaults to `sourcey.config.ts` in the
+     * Astro project root.
+     */
+    config?: string | SourceyConfig | ResolvedConfig;
+    /**
+     * Directory used to resolve relative paths when `config` is an object.
+     * Defaults to the Astro project root.
+     */
+    configDir?: string;
+    /**
+     * URL mount point within the Astro site. Defaults to the Sourcey config
+     * `baseUrl` when present, otherwise `/docs`.
+     */
+    routeBase?: string;
+    /** Override the public Sourcey `baseUrl`. Defaults to Astro `base` + `routeBase`. */
+    baseUrl?: string;
+    /** Override the public Sourcey `siteUrl`. Defaults to Astro `site`. */
+    siteUrl?: string | false;
+    /** Override Sourcey pretty URL behavior for the Astro-mounted output. */
+    prettyUrls?: PrettyUrls;
+    /** Treat changelog warnings as build errors. */
+    strictChangelog?: boolean;
+    /** Enable or configure Astro dev-server integration. */
+    dev?: boolean | {
+        enabled?: boolean;
+        generateOgImages?: boolean;
+    };
+    /** Enable or configure Astro build integration. */
+    build?: boolean | {
+        enabled?: boolean;
+        generateOgImages?: boolean;
+    };
+    /**
+     * Allow writing Sourcey at Astro's output root. Off by default because the
+     * standalone renderer prunes its output directory before writing.
+     */
+    allowRootOutput?: boolean;
+}
+interface AstroIntegration {
+    name: string;
+    hooks: {
+        "astro:config:setup"?: (options: AstroConfigSetupOptions) => void | Promise<void>;
+        "astro:build:done"?: (options: AstroBuildDoneOptions) => void | Promise<void>;
+    };
+}
+interface AstroConfigSetupOptions {
+    command: "dev" | "build" | "preview" | "sync" | string;
+    config: AstroResolvedConfig;
+    logger: AstroLogger;
+    addWatchFile: (path: URL | string) => void;
+    createCodegenDir?: () => URL;
+    updateConfig: (config: {
+        vite?: {
+            plugins?: Plugin[];
+        };
+    }) => void;
+}
+interface AstroBuildDoneOptions {
+    dir: URL;
+    logger: AstroLogger;
+}
+interface AstroResolvedConfig {
+    root: URL;
+    site?: string;
+    base?: string;
+}
+interface AstroLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug?(message: string): void;
+}
+interface PreparedAstroSourcey {
+    config: ResolvedConfig;
+    configPath?: string;
+    routeBase: string;
+    outputRoute: string;
+    devOutputDir: string;
+    watchPaths: string[];
+}
+export default function sourceyAstro(options?: SourceyAstroOptions): AstroIntegration;
+export declare function prepareAstroSourcey(options: SourceyAstroOptions, astroConfig: AstroResolvedConfig, codegenDir?: URL): Promise<PreparedAstroSourcey>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/astro/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/astro/index.ts"],"names":[],"mappings":"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"}

package/dist/astro/index.js

@@ -0,0 +1,297 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig, resolveConfigFromRaw } from "../config.js";
+import { contentTypeForPath, outputPathCandidatesForRequest, requestPathMatchesBase, } from "../renderer/static-files.js";
+import { buildSourceySite, collectSourceyWatchPaths, writeSourceySite } from "../site.js";
+import { normalizeBaseUrl, normalizeSiteUrl } from "../site-url.js";
+export default function sourceyAstro(options = {}) {
+    let prepared = null;
+    const prepareOnce = (astroConfig, codegenDir) => {
+        prepared ??= prepareAstroSourcey(options, astroConfig, codegenDir);
+        return prepared;
+    };
+    return {
+        name: "sourcey",
+        hooks: {
+            async "astro:config:setup"({ command, config, logger, addWatchFile, createCodegenDir, updateConfig, }) {
+                const codegenDir = createCodegenDir?.() ?? new URL("./.sourcey/", config.root);
+                const preparedSourcey = await prepareOnce(config, codegenDir);
+                for (const path of preparedSourcey.watchPaths) {
+                    addWatchFile(path);
+                }
+                if (command === "dev" && phaseEnabled(options.dev, true)) {
+                    updateConfig({
+                        vite: {
+                            plugins: [
+                                sourceyAstroDevPlugin({
+                                    prepared: preparedSourcey,
+                                    logger,
+                                    strictChangelog: options.strictChangelog,
+                                    generateOgImages: phaseGenerateOgImages(options.dev, false),
+                                }),
+                            ],
+                        },
+                    });
+                }
+            },
+            async "astro:build:done"({ dir, logger }) {
+                if (!phaseEnabled(options.build, true))
+                    return;
+                const fallbackConfig = {
+                    root: new URL("./", dir),
+                };
+                const preparedSourcey = await (prepared ?? prepareOnce(fallbackConfig));
+                if (preparedSourcey.outputRoute === "" && !options.allowRootOutput) {
+                    throw new Error(`sourcey/astro routeBase "/" would prune Astro's full output directory. ` +
+                        `Use routeBase: "/docs" or set allowRootOutput: true intentionally.`);
+                }
+                const outputDir = fileURLToPath(new URL(`./${preparedSourcey.outputRoute}`, dir));
+                logger.info(`Sourcey: building docs at ${displayRoute(preparedSourcey.routeBase)}`);
+                const sourceySite = await buildSourceySite({
+                    config: preparedSourcey.config,
+                    outputDir,
+                    strictChangelog: options.strictChangelog,
+                    generateOgImages: phaseGenerateOgImages(options.build, true),
+                });
+                await writeSourceySite(sourceySite);
+                await writeAstroRouteAlias({
+                    outputRoot: fileURLToPath(dir),
+                    outputDir,
+                    routeBase: preparedSourcey.routeBase,
+                });
+                logger.info(`Sourcey: wrote ${sourceySite.pageCount} page${sourceySite.pageCount === 1 ? "" : "s"}`);
+            },
+        },
+    };
+}
+export async function prepareAstroSourcey(options, astroConfig, codegenDir = new URL("./.sourcey/", astroConfig.root)) {
+    const rootDir = fileURLToPath(astroConfig.root);
+    const { config, configPath } = await loadSourceyConfigForAstro(options, rootDir);
+    const routeBase = normalizeRouteBase(options.routeBase ?? (config.baseUrl || "/docs"));
+    const baseUrl = normalizeBaseUrl(options.baseUrl ?? joinBasePaths(astroConfig.base, routeBase));
+    const siteUrl = options.siteUrl === false
+        ? undefined
+        : normalizeSiteUrl(options.siteUrl ?? astroConfig.site ?? config.siteUrl);
+    const mergedConfig = {
+        ...config,
+        baseUrl,
+        siteUrl,
+        prettyUrls: options.prettyUrls ?? config.prettyUrls,
+    };
+    const outputRoute = routeBase === "/" ? "" : `${routeBase.replace(/^\/+|\/+$/g, "")}/`;
+    const devOutputDir = fileURLToPath(new URL("./sourcey-output/", codegenDir));
+    const watchPaths = collectSourceyWatchPaths(mergedConfig, configPath);
+    return {
+        config: mergedConfig,
+        configPath,
+        routeBase,
+        outputRoute,
+        devOutputDir,
+        watchPaths,
+    };
+}
+async function loadSourceyConfigForAstro(options, rootDir) {
+    if (typeof options.config === "string") {
+        const configPath = resolveConfigPath(rootDir, options.config);
+        return { config: await loadConfig(configPath), configPath };
+    }
+    if (!options.config) {
+        const configPath = resolve(rootDir, "sourcey.config.ts");
+        return { config: await loadConfig(configPath), configPath };
+    }
+    if (isResolvedConfig(options.config)) {
+        return { config: options.config };
+    }
+    const configDir = resolve(rootDir, options.configDir ?? ".");
+    return { config: await resolveConfigFromRaw(options.config, configDir) };
+}
+function sourceyAstroDevPlugin(options) {
+    const { prepared, logger } = options;
+    let buildPromise = null;
+    let built = false;
+    async function rebuild() {
+        buildPromise ??= (async () => {
+            const sourceySite = await buildSourceySite({
+                config: prepared.config,
+                outputDir: prepared.devOutputDir,
+                strictChangelog: options.strictChangelog,
+                generateOgImages: options.generateOgImages,
+            });
+            await writeSourceySite(sourceySite);
+            built = true;
+            logger.info(`Sourcey: ready at ${displayRoute(prepared.routeBase)} (${sourceySite.pageCount} pages)`);
+        })().finally(() => {
+            buildPromise = null;
+        });
+        return buildPromise;
+    }
+    async function ensureBuilt() {
+        if (built)
+            return;
+        await rebuild();
+    }
+    return {
+        name: "sourcey:astro-dev",
+        configureServer(server) {
+            for (const path of prepared.watchPaths) {
+                server.watcher.add(path);
+            }
+            server.watcher.on("change", (file) => {
+                if (!shouldRebuildForChange(file, prepared.watchPaths))
+                    return;
+                built = false;
+                rebuild()
+                    .then(() => {
+                    server.ws.send({ type: "full-reload" });
+                })
+                    .catch((error) => {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    server.ssrFixStacktrace(err);
+                    logger.error(`Sourcey: ${err.message}`);
+                    server.ws.send({ type: "error", err: { message: err.message, stack: err.stack ?? "" } });
+                });
+            });
+            server.middlewares.use(async (req, res, next) => {
+                const url = req.url ?? "/";
+                const pathname = url.split("?", 1)[0] ?? "/";
+                if (url.startsWith("/@") ||
+                    url.startsWith("/__vite") ||
+                    url.startsWith("/node_modules/")) {
+                    return next();
+                }
+                if (!requestPathMatchesBase(pathname, prepared.config.baseUrl)) {
+                    return next();
+                }
+                try {
+                    await ensureBuilt();
+                    const file = await readGeneratedFile(prepared.devOutputDir, pathname, prepared.config.baseUrl, prepared.config.prettyUrls);
+                    if (!file)
+                        return next();
+                    res.writeHead(200, {
+                        "Content-Type": contentTypeForPath(file.outputPath),
+                        "Cache-Control": "no-cache",
+                    });
+                    res.end(file.data);
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    server.ssrFixStacktrace(err);
+                    logger.error(`Sourcey: ${err.message}`);
+                    server.ws.send({ type: "error", err: { message: err.message, stack: err.stack ?? "" } });
+                    res.writeHead(500, {
+                        "Content-Type": "text/html; charset=utf-8",
+                        "Cache-Control": "no-cache",
+                    });
+                    res.end(`<!DOCTYPE html><html><head><script type="module" src="/@vite/client"></script></head><body></body></html>`);
+                }
+            });
+        },
+    };
+}
+async function readGeneratedFile(outputDir, pathname, baseUrl, prettyUrls) {
+    for (const outputPath of outputPathCandidatesForRequest(pathname, baseUrl, prettyUrls)) {
+        const path = resolve(outputDir, outputPath);
+        if (!(await exists(path)))
+            continue;
+        const data = await readFile(path);
+        return {
+            outputPath,
+            data: shouldReadAsText(outputPath) ? data.toString("utf-8") : data,
+        };
+    }
+    return null;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveConfigPath(rootDir, config) {
+    const candidate = resolve(rootDir, config);
+    return candidate.endsWith(".ts") ? candidate : resolve(candidate, "sourcey.config.ts");
+}
+function normalizeRouteBase(value) {
+    const normalized = normalizeBaseUrl(value);
+    return normalized || "/";
+}
+function joinBasePaths(...paths) {
+    const joined = paths
+        .map((path) => path?.trim())
+        .filter((path) => Boolean(path))
+        .flatMap((path) => path.split("/"))
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .join("/");
+    return joined ? `/${joined}/` : "";
+}
+function displayRoute(routeBase) {
+    return routeBase === "/" ? "/" : routeBase.slice(0, -1);
+}
+async function writeAstroRouteAlias(options) {
+    if (options.routeBase === "/")
+        return;
+    const route = options.routeBase.replace(/^\/+|\/+$/g, "");
+    if (!route)
+        return;
+    const indexPath = resolve(options.outputDir, "index.html");
+    if (!(await exists(indexPath)))
+        return;
+    const aliasPath = resolve(options.outputRoot, `${route}.html`);
+    const html = await readFile(indexPath, "utf-8");
+    await mkdir(dirname(aliasPath), { recursive: true });
+    await writeFile(aliasPath, renderAstroRouteAlias(html, options.routeBase));
+}
+function renderAstroRouteAlias(html, routeBase) {
+    const basePath = routeBase.endsWith("/") ? routeBase : `${routeBase}/`;
+    return html
+        .replace(/\b(href|src)="([^"]+)"/g, (match, attr, value) => {
+        if (!shouldPrefixAliasUrl(value))
+            return match;
+        return `${attr}="${basePath}${value.replace(/^\.\//, "")}"`;
+    })
+        .replace(/(<meta\s+name="sourcey-search"\s+content=")([^"]+)(")/g, (match, prefix, value, suffix) => {
+        if (!shouldPrefixAliasUrl(value))
+            return match;
+        return `${prefix}${basePath}${value.replace(/^\.\//, "")}${suffix}`;
+    });
+}
+function shouldPrefixAliasUrl(value) {
+    return !/^(?:#|\/|[a-z][a-z0-9+.-]*:)/i.test(value);
+}
+function isResolvedConfig(config) {
+    return Array.isArray(config.tabs);
+}
+function phaseEnabled(phase, defaultEnabled) {
+    if (typeof phase === "boolean")
+        return phase;
+    return phase?.enabled ?? defaultEnabled;
+}
+function phaseGenerateOgImages(phase, defaultEnabled) {
+    return typeof phase === "object" ? phase.generateOgImages ?? defaultEnabled : defaultEnabled;
+}
+function shouldRebuildForChange(file, watchPaths) {
+    if (watchPaths.includes(file))
+        return true;
+    const ext = extname(file);
+    return ext === ".md" || ext === ".mdx" || ext === ".json" || ext === ".yml" || ext === ".yaml";
+}
+function shouldReadAsText(outputPath) {
+    switch (extname(outputPath).toLowerCase()) {
+        case ".html":
+        case ".css":
+        case ".js":
+        case ".mjs":
+        case ".json":
+        case ".svg":
+        case ".txt":
+        case ".xml":
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/cli.js

@@ -8,6 +8,7 @@ import { runIntrospector, GodocIntrospectorError } from "./core/godoc-introspect
 import { GODOC_SCHEMA_VERSION } from "./core/godoc-types.js";
 import { init } from "./init.js";
 import { formatChangelogDiagnostic, formatGodocDiagnostic, formatRustdocDiagnostic, } from "./site-assembly.js";
+import { findPlaceholderServerUrls } from "./utils/server-warnings.js";
 import pkg from "../package.json" with { type: "json" };
 const build = defineCommand({
     meta: {
@@ -63,6 +64,7 @@ const build = defineCommand({
                     strictChangelog: args.strictChangelog,
                 });
                 if (!args.quiet) {
+                    logQuickBuildServerWarnings(result.spec);
                     logChangelogDiagnostics(result.changelogDiagnostics);
                     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
                     console.log(`  Spec:       ${result.spec.info.title} v${result.spec.info.version}`);
@@ -308,6 +310,12 @@ function logRustdocDiagnostics(diagnostics) {
         writer(`  ${formatRustdocDiagnostic(diagnostic)}`);
     }
 }
+function logQuickBuildServerWarnings(spec) {
+    const placeholderUrls = findPlaceholderServerUrls(spec);
+    for (const url of placeholderUrls) {
+        console.warn(`  Warning: quick build is using placeholder server URL "${url}". Generated code samples will target that host. Use sourcey.config.ts or correct the source document before publishing.`);
+    }
+}
 function parsePort(value) {
     if (!/^\d+$/.test(value)) {
         throw new Error(`Invalid port "${value}". Expected an integer from 1 to 65535.`);

package/dist/client/scroll-tracker.js

@@ -1,12 +1,12 @@
 // Scroll tracker — highlights the active sidebar nav link as user scrolls.
 //
 // Observes [data-traverse-target] section anchors and toggles .active
-// on the matching #nav .nav-link. All visual styling is in sourcey.css;
+// on the matching #nav fragment link. All visual styling is in sourcey.css;
 // this file only manages the class.
 (function () {
   function init() {
     var navbar = document.getElementById('navbar');
-    var navLinks = document.querySelectorAll('#nav .nav-link');
+    var navLinks = document.querySelectorAll('#nav .nav-link, #nav .nav-group-link');
     var targets = document.querySelectorAll('[data-traverse-target]');
 
     // For prose pages, also track heading elements that TOC links point to
@@ -113,7 +113,7 @@
     if (tocEl) tocEl.addEventListener('click', function (e) { handleAnchorClick(e, '.toc-item'); });
 
     var navEl = document.getElementById('nav');
-    if (navEl) navEl.addEventListener('click', function (e) { handleAnchorClick(e, '.nav-link'); });
+    if (navEl) navEl.addEventListener('click', function (e) { handleAnchorClick(e, '.nav-link, .nav-group-link'); });
 
     // Use scroll event for reliable activation at all positions.
     function onScroll() {