@reicek/neataptic-ts 0.1.25 → 0.1.26

package/scripts/render-docs-html/render-docs-html.assets.ts

@@ -0,0 +1,54 @@
+/*
+ * Static asset bootstrapping for generated HTML docs.
+ *
+ * Theme CSS and the landing-page hero image are stable assets that should be
+ * prepared before markdown pages are rendered. Keeping that work here prevents
+ * the root renderer from mixing file-copy policy with page assembly.
+ */
+
+import path from 'path';
+import fs from 'fs-extra';
+
+import { DOCS_DIR } from './render-docs-html.shared.js';
+
+const THEME_CSS_SOURCE_PATH = path.resolve('scripts', 'assets', 'theme.css');
+const THEME_CSS_OUTPUT_PATH = path.join(DOCS_DIR, 'assets', 'theme.css');
+const NN_IMAGE_SOURCE_PATH = path.resolve('nn.jpg');
+const NN_IMAGE_FALLBACK_SOURCE_PATH = path.resolve(
+  'scripts',
+  'assets',
+  'nn.jpg',
+);
+const NN_IMAGE_OUTPUT_PATH = path.join(DOCS_DIR, 'nn.jpg');
+
+/** Ensures static non-Mermaid assets exist under the generated docs tree. */
+export async function ensureRenderDocsAssets(): Promise<void> {
+  await ensureThemeCss();
+  await ensureRootHeroImage();
+}
+
+/** Copies the docs theme stylesheet into the published assets tree. */
+async function ensureThemeCss(): Promise<void> {
+  await fs.ensureDir(path.dirname(THEME_CSS_OUTPUT_PATH));
+  await fs.copyFile(THEME_CSS_SOURCE_PATH, THEME_CSS_OUTPUT_PATH);
+}
+
+/**
+ * Copies the root README hero image so `/docs/README.md` can keep using the
+ * same `nn.jpg` reference after publication.
+ */
+async function ensureRootHeroImage(): Promise<void> {
+  const hasRootImage = await fs.pathExists(NN_IMAGE_SOURCE_PATH);
+  const hasFallbackImage = await fs.pathExists(NN_IMAGE_FALLBACK_SOURCE_PATH);
+  const sourcePath = hasRootImage
+    ? NN_IMAGE_SOURCE_PATH
+    : hasFallbackImage
+      ? NN_IMAGE_FALLBACK_SOURCE_PATH
+      : undefined;
+
+  if (!sourcePath) {
+    return;
+  }
+
+  await fs.copyFile(sourcePath, NN_IMAGE_OUTPUT_PATH);
+}

package/scripts/render-docs-html/render-docs-html.mermaid.ts

@@ -0,0 +1,245 @@
+/*
+ * Mermaid asset bootstrapping and validation for generated HTML docs.
+ *
+ * This chapter owns both sides of Mermaid handling: copying the browser bundle
+ * needed at runtime and treating invalid fenced diagrams as a build failure
+ * during docs generation.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'path';
+import fs from 'fs-extra';
+
+import { escapeHtml, DOCS_DIR } from './render-docs-html.shared.js';
+import type { MermaidBlockReference } from './render-docs-html.types.js';
+
+const MERMAID_MODULE_SOURCE_PATH = path.resolve(
+  'node_modules',
+  'mermaid',
+  'dist',
+  'mermaid.esm.min.mjs',
+);
+const MERMAID_DIST_SOURCE_DIR = path.resolve('node_modules', 'mermaid', 'dist');
+const MERMAID_DIST_OUTPUT_DIR = path.join(DOCS_DIR, 'assets', 'vendor');
+const MERMAID_CLI_SCRIPT_PATH = path.resolve(
+  'dist-docs',
+  'scripts',
+  'mermaid-cli.js',
+);
+const MERMAID_VALIDATION_CONCURRENCY = Math.max(
+  1,
+  Math.min(
+    4,
+    typeof os.availableParallelism === 'function'
+      ? os.availableParallelism() - 1
+      : 4,
+  ),
+);
+
+interface MermaidValidationTask {
+  mermaidBlock: MermaidBlockReference;
+  tempInputPath: string;
+}
+
+/** Ensures the Mermaid browser bundle is copied into the published docs tree. */
+export async function ensureMermaidBrowserAssets(): Promise<void> {
+  const hasMermaidModule = await fs.pathExists(MERMAID_MODULE_SOURCE_PATH);
+  if (!hasMermaidModule) {
+    return;
+  }
+
+  await fs.ensureDir(MERMAID_DIST_OUTPUT_DIR);
+  await fs.copy(MERMAID_DIST_SOURCE_DIR, MERMAID_DIST_OUTPUT_DIR, {
+    overwrite: true,
+  });
+}
+
+/** Builds the client-side Mermaid bootstrap script for one generated page. */
+export function buildMermaidBootstrapScript(relToRoot: string): string {
+  const mermaidModuleHref =
+    (relToRoot ? `${relToRoot}/` : '') + 'assets/vendor/mermaid.esm.min.mjs';
+
+  return `<script type="module">
+import mermaid from "${mermaidModuleHref}";
+
+mermaid.initialize({
+  startOnLoad: false,
+  securityLevel: 'loose',
+  theme: 'base',
+  themeVariables: {
+    darkMode: true,
+    background: '#121a24',
+    primaryColor: '#102131',
+    primaryTextColor: '#d7e4f3',
+    primaryBorderColor: '#5ec8ff',
+    secondaryColor: '#0f1722',
+    secondaryTextColor: '#d7e4f3',
+    secondaryBorderColor: '#5ec8ff',
+    tertiaryColor: '#16283a',
+    tertiaryTextColor: '#d7e4f3',
+    tertiaryBorderColor: '#ffbf69',
+    mainBkg: '#0f1722',
+    nodeBorder: '#5ec8ff',
+    clusterBkg: '#102131',
+    clusterBorder: '#5ec8ff',
+    lineColor: '#5ec8ff',
+    edgeLabelBackground: '#0f1722',
+    textColor: '#d7e4f3',
+    fontFamily: 'Open Sans, sans-serif'
+  }
+});
+
+try {
+  await mermaid.run({ querySelector: '.mermaid-diagram' });
+} catch (error) {
+  console.error('[docs] Mermaid render failed.', error);
+}
+</script>`;
+}
+
+/** Collects Mermaid fenced blocks from one markdown page. */
+export function collectMermaidBlocks(
+  markdown: string,
+  readmePath: string,
+): MermaidBlockReference[] {
+  const mermaidBlocks: MermaidBlockReference[] = [];
+  const mermaidFencePattern = /^```mermaid[^\n]*\r?\n([\s\S]*?)^```\s*$/gm;
+  let mermaidMatch = mermaidFencePattern.exec(markdown);
+
+  while (mermaidMatch) {
+    mermaidBlocks.push({
+      readmePath,
+      blockNumber: mermaidBlocks.length + 1,
+      diagram: mermaidMatch[1].trim(),
+    });
+    mermaidMatch = mermaidFencePattern.exec(markdown);
+  }
+
+  return mermaidBlocks;
+}
+
+/** Validates every collected Mermaid block before HTML generation proceeds. */
+export async function validateMermaidBlocks(
+  mermaidBlocks: readonly MermaidBlockReference[],
+): Promise<void> {
+  if (mermaidBlocks.length === 0) {
+    return;
+  }
+
+  const uniqueMermaidBlocks = resolveUniqueMermaidBlocks(mermaidBlocks);
+  const tempDirectoryPath = await mkdtemp(
+    path.join(os.tmpdir(), 'neatapticts-docs-mermaid-'),
+  );
+
+  try {
+    const mermaidValidationTasks = uniqueMermaidBlocks.map(
+      (mermaidBlock, blockIndex) => ({
+        mermaidBlock,
+        tempInputPath: path.join(
+          tempDirectoryPath,
+          `diagram-${blockIndex + 1}.mmd`,
+        ),
+      }),
+    );
+
+    await Promise.all(
+      mermaidValidationTasks.map((mermaidValidationTask) =>
+        fs.writeFile(
+          mermaidValidationTask.tempInputPath,
+          mermaidValidationTask.mermaidBlock.diagram,
+          'utf8',
+        ),
+      ),
+    );
+    await runMermaidValidationPool(mermaidValidationTasks);
+  } finally {
+    await rm(tempDirectoryPath, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Resolves one representative block for each unique Mermaid source string.
+ *
+ * Many generated README surfaces repeat the same diagrams, so validating each
+ * unique source only once avoids redundant parser work.
+ *
+ * @param mermaidBlocks - Mermaid blocks collected from generated docs surfaces.
+ * @returns Representative Mermaid blocks keyed by unique diagram text.
+ */
+function resolveUniqueMermaidBlocks(
+  mermaidBlocks: readonly MermaidBlockReference[],
+): MermaidBlockReference[] {
+  const uniqueMermaidBlocksByDiagram = new Map<string, MermaidBlockReference>();
+
+  for (const mermaidBlock of mermaidBlocks) {
+    if (!uniqueMermaidBlocksByDiagram.has(mermaidBlock.diagram)) {
+      uniqueMermaidBlocksByDiagram.set(mermaidBlock.diagram, mermaidBlock);
+    }
+  }
+
+  return [...uniqueMermaidBlocksByDiagram.values()];
+}
+
+/** Validates Mermaid diagrams through a bounded parallel worker pool. */
+async function runMermaidValidationPool(
+  mermaidValidationTasks: readonly MermaidValidationTask[],
+): Promise<void> {
+  let nextTaskIndex = 0;
+  const workerCount = Math.min(
+    MERMAID_VALIDATION_CONCURRENCY,
+    mermaidValidationTasks.length,
+  );
+
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (nextTaskIndex < mermaidValidationTasks.length) {
+        const mermaidValidationTask = mermaidValidationTasks[nextTaskIndex];
+        nextTaskIndex += 1;
+        await runMermaidValidation(mermaidValidationTask);
+      }
+    }),
+  );
+}
+
+/** Runs the Mermaid CLI validator for one diagram source file. */
+async function runMermaidValidation(
+  mermaidValidationTask: MermaidValidationTask,
+): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const childProcess = spawn(
+      process.execPath,
+      [
+        MERMAID_CLI_SCRIPT_PATH,
+        'validate',
+        '--input',
+        mermaidValidationTask.tempInputPath,
+      ],
+      { stdio: 'inherit' },
+    );
+
+    childProcess.once('exit', (exitCode, signal) => {
+      if (exitCode === 0) {
+        resolve();
+        return;
+      }
+
+      const relativeReadmePath = path.relative(
+        process.cwd(),
+        mermaidValidationTask.mermaidBlock.readmePath,
+      );
+      reject(
+        new Error(
+          `Invalid Mermaid diagram in ${relativeReadmePath} (block ${mermaidValidationTask.mermaidBlock.blockNumber}). Mermaid CLI exited with code ${exitCode ?? 'null'}${signal ? ` and signal ${signal}` : ''}.`,
+        ),
+      );
+    });
+    childProcess.once('error', reject);
+  });
+}
+
+/** Renders Mermaid fenced blocks as safe placeholder HTML before client boot. */
+export function renderMermaidDiagramPlaceholder(diagram: string): string {
+  return `<pre class="mermaid mermaid-diagram">${escapeHtml(diagram)}</pre>`;
+}

package/scripts/{render-docs-html.sidebar.ts → render-docs-html/render-docs-html.navigation.ts}

@@ -1,13 +1,17 @@
 /*
  * Owns the generated docs sidebar contract.
  *
- * The main HTML renderer only needs to decide which page is being emitted and
- * which docs directories were published. This helper turns that data into the
- * left-nav learning path: examples first for onboarding, grouped docs pages for
- * reference reading, and a depth-aware rail that stays visually continuous as
- * readers move between overview pages and nested deep dives.
+ * This chapter turns the published docs page set into the left-nav learning
+ * path: examples first for onboarding, grouped docs pages for reference
+ * reading, and a depth-aware rail that remains visually continuous.
  */
 
+import type {
+  DocsSidebarRenderContext,
+  PageMeta,
+  SidebarRenderContext,
+} from './render-docs-html.types.js';
+
 interface ExampleNavLink {
   dir: string;
   label: string;
@@ -30,34 +34,6 @@ interface PipeNavEntry {
   cssClass?: string;
 }
 
-interface SidebarRenderHelpers {
-  generatedPageDirectories: ReadonlySet<string>;
-  hasPublishedDocsPage: (
-    relDir: string,
-    generatedPageDirectories: ReadonlySet<string>,
-  ) => boolean;
-  buildRelativeDocsHref: (currentDir: string, targetDir: string) => string;
-  escapeHtml: (value: string) => string;
-}
-
-/** Minimal page shape needed to assemble the docs sidebar groups. */
-export interface SidebarPageMeta {
-  relDir: string;
-}
-
-/**
- * Shared render context for sidebar fragments that need publication checks and
- * stable relative links.
- */
-export interface SidebarRenderContext extends SidebarRenderHelpers {
-  currentDir: string;
-}
-
-/** Render context for the full docs sidebar, including the grouped page set. */
-export interface DocsSidebarRenderContext extends SidebarRenderContext {
-  pages: readonly SidebarPageMeta[];
-}
-
 const EXAMPLES_OVERVIEW_DIR = 'examples';
 const SIDEBAR_GROUP_ORDER = [
   'root',
@@ -216,16 +192,7 @@ const EXAMPLE_DEMOS: readonly ExampleNavDemo[] = [
   },
 ];
 
-/**
- * Render the compact examples list used on the root-page table of contents.
- *
- * This keeps the landing page aligned with the learning-path plan: readers see
- * the examples overview first, then the strongest demo entrypoints, without
- * needing the full sidebar card treatment.
- *
- * @param context - Link and publication helpers for the page being rendered.
- * @returns A compact pipe-nav list for published example docs, or an empty list.
- */
+/** Renders the compact examples list used on the root-page table of contents. */
 export function buildExamplesTocLinksHtml(
   context: SidebarRenderContext,
 ): string {
@@ -262,25 +229,18 @@ export function buildExamplesTocLinksHtml(
   return buildPipeNavListHtml(context, entries, 'pipe-nav-list-compact');
 }
 
-/**
- * Render the full left docs sidebar with the examples-first learning path.
- *
- * The sidebar owns the teaching order for generated docs pages. Runnable
- * examples stay at the top because they are the fastest route to first success,
- * while the remaining pages are grouped into reference sections that make sense
- * once a reader is already oriented.
- *
- * @param context - The published page set, current page, and link helpers.
- * @returns The full sidebar section list for the current docs page.
- */
+/** Renders the full left docs sidebar with the examples-first learning path. */
 export function buildDocsSidebarHtml(
   context: DocsSidebarRenderContext,
 ): string {
-  const groupsMap = new Map<string, { name: string; items: SidebarPageMeta[] }>();
+  const groupsMap = new Map<string, { name: string; items: PageMeta[] }>();
 
   for (const page of context.pages) {
     const segment = page.relDir.split('/')[0] || 'root';
-    if (segment === 'examples') continue;
+    if (segment === 'examples') {
+      continue;
+    }
+
     if (!groupsMap.has(segment)) {
       groupsMap.set(segment, { name: segment, items: [] });
     }
@@ -298,8 +258,11 @@ export function buildDocsSidebarHtml(
         rightGroup.name as (typeof SIDEBAR_GROUP_ORDER)[number],
       );
       const leftRank = leftOrder === -1 ? Number.MAX_SAFE_INTEGER : leftOrder;
-      const rightRank = rightOrder === -1 ? Number.MAX_SAFE_INTEGER : rightOrder;
-      return leftRank - rightRank || leftGroup.name.localeCompare(rightGroup.name);
+      const rightRank =
+        rightOrder === -1 ? Number.MAX_SAFE_INTEGER : rightOrder;
+      return (
+        leftRank - rightRank || leftGroup.name.localeCompare(rightGroup.name)
+      );
     })
     .map((group) => {
       const items = group.items.toSorted((leftPage, rightPage) =>
@@ -317,7 +280,7 @@ export function buildDocsSidebarHtml(
       }
 
       return `<li class="group"><div class="g-head">${context.escapeHtml(
-        group.name,
+        formatSidebarGroupName(group.name),
       )}</div>${buildPipeNavListHtml(
         context,
         buildGroupPipeEntries(items, context.currentDir),
@@ -328,16 +291,7 @@ export function buildDocsSidebarHtml(
   return `<ul class="sidebar-sections">${examplesSidebarHtml}${groupsHtml}</ul>`;
 }
 
-/**
- * Render the example showcase cards that anchor the sidebar learning path.
- *
- * Each demo keeps a recommended reading order and a separate deep-dive list so
- * the sidebar can teach progression without flattening every page into one long
- * undifferentiated navigation block.
- *
- * @param context - Link and publication helpers for the page being rendered.
- * @returns The examples-first sidebar section, or an empty string when hidden.
- */
+/** Renders the example showcase cards that anchor the sidebar learning path. */
 function buildExamplesSidebarHtml(context: SidebarRenderContext): string {
   const examplesOverviewLink = buildPipeNavListHtml(
     context,
@@ -358,64 +312,98 @@ function buildExamplesSidebarHtml(context: SidebarRenderContext): string {
     'pipe-nav-list-priority',
   );
 
-  const demoCardsHtml = EXAMPLE_DEMOS.map((demo) => {
-    const readingOrderLinksHtml = buildPipeNavListHtml(
-      context,
-      demo.readingOrder
-        .filter((entry) =>
-          context.hasPublishedDocsPage(entry.dir, context.generatedPageDirectories),
-        )
-        .map((entry) => ({
-          label: entry.label,
-          targetDir: entry.dir,
+  const showExpandedExampleShowcase =
+    context.currentDir === '' ||
+    context.currentDir === EXAMPLES_OVERVIEW_DIR ||
+    context.currentDir.startsWith('examples/');
+  const compactExamplesLinksHtml = showExpandedExampleShowcase
+    ? ''
+    : buildPipeNavListHtml(
+        context,
+        EXAMPLE_DEMOS.filter((demo) =>
+          context.hasPublishedDocsPage(
+            `${demo.dir}/docs`,
+            context.generatedPageDirectories,
+          ),
+        ).map((demo) => ({
+          label: demo.label,
+          targetDir: `${demo.dir}/docs`,
           depth: 0,
-          isCurrent: context.currentDir === entry.dir,
-        })),
-    );
-    const deepDiveLinksHtml = buildPipeNavListHtml(
-      context,
-      demo.deepDives
-        .filter((entry) =>
-          context.hasPublishedDocsPage(entry.dir, context.generatedPageDirectories),
-        )
-        .map((entry) => ({
-          label: entry.label,
-          targetDir: entry.dir,
-          depth: 1,
-          isCurrent: context.currentDir === entry.dir,
+          isCurrent: context.currentDir === `${demo.dir}/docs`,
         })),
-    );
-    const isCurrentDemo =
-      context.currentDir === demo.dir ||
-      context.currentDir.startsWith(`${demo.dir}/`) ||
-      context.currentDir.startsWith(`${demo.dir}/docs`);
-
-    if (!readingOrderLinksHtml && !deepDiveLinksHtml) {
-      return '';
-    }
+        'pipe-nav-list-compact',
+      );
 
-    return `<li class="nav-demo-card${isCurrentDemo ? ' is-current-demo' : ''}"><div class="nav-demo-meta"><div class="nav-demo-eyebrow">${context.escapeHtml(
-      demo.eyebrow,
-    )}</div><div class="nav-demo-title">${context.escapeHtml(
-      demo.label,
-    )}</div><p class="nav-demo-description">${context.escapeHtml(
-      demo.description,
-    )}</p></div><div class="nav-demo-cluster"><div class="nav-cluster-title">Recommended path</div>${readingOrderLinksHtml}</div>${
-      deepDiveLinksHtml
-        ? `<div class="nav-demo-cluster nav-demo-cluster-secondary"><div class="nav-cluster-title">Deep dives</div>${deepDiveLinksHtml}</div>`
-        : ''
-    }</li>`;
-  })
-    .filter(Boolean)
-    .join('');
+  const demoCardsHtml = showExpandedExampleShowcase
+    ? EXAMPLE_DEMOS.map((demo) => {
+        const readingOrderLinksHtml = buildPipeNavListHtml(
+          context,
+          demo.readingOrder
+            .filter((entry) =>
+              context.hasPublishedDocsPage(
+                entry.dir,
+                context.generatedPageDirectories,
+              ),
+            )
+            .map((entry) => ({
+              label: entry.label,
+              targetDir: entry.dir,
+              depth: 0,
+              isCurrent: context.currentDir === entry.dir,
+            })),
+        );
+        const deepDiveLinksHtml = buildPipeNavListHtml(
+          context,
+          demo.deepDives
+            .filter((entry) =>
+              context.hasPublishedDocsPage(
+                entry.dir,
+                context.generatedPageDirectories,
+              ),
+            )
+            .map((entry) => ({
+              label: entry.label,
+              targetDir: entry.dir,
+              depth: 1,
+              isCurrent: context.currentDir === entry.dir,
+            })),
+        );
+        const isCurrentDemo =
+          context.currentDir === demo.dir ||
+          context.currentDir.startsWith(`${demo.dir}/`) ||
+          context.currentDir.startsWith(`${demo.dir}/docs`);
+
+        if (!readingOrderLinksHtml && !deepDiveLinksHtml) {
+          return '';
+        }
+
+        return `<li class="nav-demo-card${isCurrentDemo ? ' is-current-demo' : ''}"><div class="nav-demo-meta"><div class="nav-demo-eyebrow">${context.escapeHtml(
+          demo.eyebrow,
+        )}</div><div class="nav-demo-title">${context.escapeHtml(
+          demo.label,
+        )}</div><p class="nav-demo-description">${context.escapeHtml(
+          demo.description,
+        )}</p></div><div class="nav-demo-cluster"><div class="nav-cluster-title">Recommended path</div>${readingOrderLinksHtml}</div>${
+          deepDiveLinksHtml
+            ? `<div class="nav-demo-cluster nav-demo-cluster-secondary"><div class="nav-cluster-title">Deep dives</div>${deepDiveLinksHtml}</div>`
+            : ''
+        }</li>`;
+      })
+        .filter(Boolean)
+        .join('')
+    : '';
 
-  if (!examplesOverviewLink && !demoCardsHtml) return '';
+  if (!examplesOverviewLink && !compactExamplesLinksHtml && !demoCardsHtml) {
+    return '';
+  }
 
-  return `<li class="group group-priority"><div class="g-head">Start With Examples</div><p class="group-copy">The demos are the fastest way to learn the library in the order a first-time reader can actually absorb.</p><div class="nav-priority-links">${examplesOverviewLink}</div><ul class="nav-demo-showcase">${demoCardsHtml}</ul></li>`;
+  return `<li class="group group-priority"><div class="g-head">Start With Examples</div><p class="group-copy">The demos are the fastest way to learn the library in the order a first-time reader can actually absorb.</p><div class="nav-priority-links">${examplesOverviewLink}${compactExamplesLinksHtml}</div>${
+    demoCardsHtml ? `<ul class="nav-demo-showcase">${demoCardsHtml}</ul>` : ''
+  }</li>`;
 }
 
 function buildGroupPipeEntries(
-  items: readonly SidebarPageMeta[],
+  items: readonly PageMeta[],
   currentDir: string,
 ): PipeNavEntry[] {
   return items
@@ -425,7 +413,7 @@ function buildGroupPipeEntries(
     .map((page) => {
       const relativeSegments = page.relDir.split('/').slice(1);
       return {
-        label: relativeSegments.at(-1) ?? 'Overview',
+        label: formatGroupEntryLabel(relativeSegments),
         targetDir: page.relDir,
         depth: Math.max(0, relativeSegments.length - 1),
         isCurrent: page.relDir === currentDir,
@@ -434,17 +422,35 @@ function buildGroupPipeEntries(
 }
 
 /**
- * Render the fixed-width rail cells that anchor one sidebar row.
- *
- * Depth is represented by layout boxes rather than text glyph stacks. That
- * gives CSS a stable column contract for the vertical rail and connector line,
- * which prevents the left path from breaking when fonts, line-height, or
- * example cluster boundaries change.
- *
- * @param depth - Logical nesting depth for the entry being rendered.
- * @param isFooter - Whether the cells belong to the footer row that closes the list.
- * @returns The rail-cell markup for one sidebar row.
+ * Formats sidebar labels so overview pages read clearly and deep pages are not
+ * reduced to ambiguous repeated leaf names.
  */
+function formatGroupEntryLabel(relativeSegments: readonly string[]): string {
+  if (relativeSegments.length === 0) {
+    return 'Overview';
+  }
+
+  const leafLabel = formatSidebarGroupName(
+    relativeSegments.at(-1) ?? 'Overview',
+  );
+  if (relativeSegments.length === 1) {
+    return leafLabel;
+  }
+
+  const parentLabel = formatSidebarGroupName(relativeSegments.at(-2) ?? '');
+  return `${parentLabel} / ${leafLabel}`;
+}
+
+/** Formats a sidebar group or segment name into a human-readable label. */
+function formatSidebarGroupName(segment: string): string {
+  return segment
+    .split(/[-_]/g)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/** Renders the fixed-width rail cells that anchor one sidebar row. */
 function buildPipeRailCellsHtml(depth: number, isFooter = false): string {
   const railDepth = Math.max(0, depth);
 
@@ -462,24 +468,15 @@ function buildPipeRailCellsHtml(depth: number, isFooter = false): string {
   }).join('');
 }
 
-/**
- * Render one pipe-nav list using box-based rail columns for visual continuity.
- *
- * Entries provide a logical depth value rather than nested list markup. That
- * keeps the DOM shallow while still giving the theme enough structure to draw a
- * continuous rail through overview links, recommended paths, and deep dives.
- *
- * @param context - Link and publication helpers for the page being rendered.
- * @param entries - Sidebar links with the depth contract already resolved.
- * @param listClass - Optional modifier class for compact or priority variants.
- * @returns One pipe-nav list plus a footer rail that finishes the visual track.
- */
+/** Renders one rail-based pipe navigation list. */
 function buildPipeNavListHtml(
   context: SidebarRenderContext,
   entries: readonly PipeNavEntry[],
   listClass = '',
 ): string {
-  if (entries.length === 0) return '';
+  if (entries.length === 0) {
+    return '';
+  }
 
   const itemsHtml = entries
     .map((entry) => {
@@ -510,4 +507,4 @@ function buildPipeNavListHtml(
     lastEntryDepth,
     true,
   )}</span></li></ul>`;
-}
+}