@f5-sales-demo/docs-theme 3.9.46 → 3.9.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f5-sales-demo/docs-theme",
-  "version": "3.9.46",
+  "version": "3.9.47",
   "description": "F5 Distributed Cloud branded Starlight documentation theme",
   "type": "module",
   "engines": {

package/src/utils/subcategory-sidebar.test.ts

@@ -1,5 +1,21 @@
-import { describe, expect, it } from 'vitest';
-import { filePathToSlug } from './subcategory-sidebar';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { buildSubcategorySidebar, filePathToSlug } from './subcategory-sidebar';
+
+const workspaces: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(workspaces.splice(0).map((workspace) => rm(workspace, { force: true, recursive: true })));
+});
+
+async function writeDoc(root: string, relativePath: string, title: string, order?: number): Promise<void> {
+  const filePath = path.join(root, relativePath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const sidebar = order === undefined ? '' : `sidebar:\n  order: ${order}\n`;
+  await writeFile(filePath, `---\ntitle: ${title}\n${sidebar}---\n\nContent.\n`);
+}
 
 describe('filePathToSlug', () => {
   it('lowercases capitalised path segments to match Starlight entry slugs', () => {
@@ -23,3 +39,83 @@ describe('filePathToSlug', () => {
     expect(filePathToSlug('Enhancements\\foo.mdx')).toBe('/enhancements/foo/');
   });
 });
+
+describe('buildSubcategorySidebar without subcategories', () => {
+  it('preserves three directory levels, index landings, and sidebar order', async () => {
+    const workspace = await mkdtemp(path.join(tmpdir(), 'docs-theme-sidebar-'));
+    workspaces.push(workspace);
+    const contentDir = path.join(workspace, 'content');
+    const docsDir = path.join(contentDir, 'en');
+
+    await writeDoc(docsDir, 'index.mdx', 'Home', 0);
+    await writeDoc(docsDir, 'reference/index.mdx', 'Reference', 1);
+    await writeDoc(docsDir, 'demo/index.mdx', 'Demo', 2);
+    await writeDoc(docsDir, 'demo/verify.mdx', 'Verify', 20);
+    await writeDoc(docsDir, 'demo/deploy.mdx', 'Deploy', 10);
+    await writeDoc(docsDir, 'demo/troubleshooting/index.mdx', 'Troubleshooting', 5);
+    await writeDoc(docsDir, 'demo/troubleshooting/bgp/index.mdx', 'BGP', 1);
+    await writeDoc(docsDir, 'demo/troubleshooting/bgp/routes.mdx', 'Routes', 1);
+
+    const sidebar = buildSubcategorySidebar(contentDir);
+
+    expect(sidebar?.[0]).toMatchObject({ label: 'Overview', link: '/' });
+    expect(sidebar?.slice(1)).toEqual([
+      {
+        label: 'Reference',
+        collapsed: true,
+        translations: expect.any(Object),
+        items: [{ label: 'Overview', slug: 'reference', translations: expect.any(Object) }],
+      },
+      {
+        label: 'Demo',
+        collapsed: true,
+        items: [
+          { label: 'Overview', slug: 'demo', translations: expect.any(Object) },
+          {
+            label: 'Troubleshooting',
+            collapsed: true,
+            translations: expect.any(Object),
+            items: [
+              { label: 'Overview', slug: 'demo/troubleshooting', translations: expect.any(Object) },
+              {
+                label: 'BGP',
+                collapsed: true,
+                items: [
+                  { label: 'Overview', slug: 'demo/troubleshooting/bgp', translations: expect.any(Object) },
+                  { slug: 'demo/troubleshooting/bgp/routes' },
+                ],
+              },
+            ],
+          },
+          { slug: 'demo/deploy' },
+          { slug: 'demo/verify' },
+        ],
+      },
+    ]);
+  });
+
+  it('falls back to title ordering when sidebar order is absent', async () => {
+    const workspace = await mkdtemp(path.join(tmpdir(), 'docs-theme-sidebar-'));
+    workspaces.push(workspace);
+    const contentDir = path.join(workspace, 'content');
+
+    await writeDoc(contentDir, 'guides/index.mdx', 'Guides');
+    await writeDoc(contentDir, 'guides/z-last.mdx', 'Zebra');
+    await writeDoc(contentDir, 'guides/a-first.mdx', 'Alpha');
+
+    const sidebar = buildSubcategorySidebar(contentDir);
+
+    expect(sidebar).toEqual([
+      {
+        label: 'Guides',
+        collapsed: true,
+        translations: expect.any(Object),
+        items: [
+          { label: 'Overview', slug: 'guides', translations: expect.any(Object) },
+          { slug: 'guides/a-first' },
+          { slug: 'guides/z-last' },
+        ],
+      },
+    ]);
+  });
+});

package/src/utils/subcategory-sidebar.ts

@@ -6,10 +6,17 @@ import { sidebarTranslations } from '../i18n/translations.ts';
 /**
  * Starlight sidebar config types (simplified).
  */
-type SidebarLink = { label: string; link?: string; slug?: string; translations?: Record<string, string> };
+type SidebarLink = { label?: string; link?: string; slug?: string; translations?: Record<string, string> };
 type SidebarGroup = { label: string; items: SidebarItem[]; collapsed?: boolean; translations?: Record<string, string> };
 type SidebarItem = SidebarLink | SidebarGroup;
 
+interface OrderedSidebarItem {
+  item: SidebarItem;
+  order: number | undefined;
+  sortLabel: string;
+  sortPath: string;
+}
+
 type DocType = 'resource' | 'data-source' | 'guide' | 'function';
 
 interface DocEntry {
@@ -77,6 +84,105 @@ function kebabToTitleCase(kebab: string): string {
     .join(' ');
 }
 
+function readNavigationMetadata(filePath: string, fallbackTitle: string): { title: string; order: number | undefined } {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const frontmatter = matter(raw).data as Record<string, unknown>;
+    const title =
+      typeof frontmatter.title === 'string' && frontmatter.title.trim()
+        ? frontmatter.title.trim()
+        : typeof frontmatter.page_title === 'string' && frontmatter.page_title.trim()
+          ? frontmatter.page_title.trim()
+          : fallbackTitle;
+    const sidebar = frontmatter.sidebar;
+    const order =
+      typeof sidebar === 'object' &&
+      sidebar !== null &&
+      'order' in sidebar &&
+      typeof sidebar.order === 'number' &&
+      Number.isFinite(sidebar.order)
+        ? sidebar.order
+        : undefined;
+    return { title, order };
+  } catch {
+    return { title: fallbackTitle, order: undefined };
+  }
+}
+
+function compareOrderedSidebarItems(a: OrderedSidebarItem, b: OrderedSidebarItem): number {
+  const orderDifference = (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY);
+  if (orderDifference !== 0) return orderDifference;
+  const labelDifference = a.sortLabel.localeCompare(b.sortLabel);
+  return labelDifference !== 0 ? labelDifference : a.sortPath.localeCompare(b.sortPath);
+}
+
+function buildDirectorySidebar(dirPath: string, scanDir: string): OrderedSidebarItem | undefined {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+
+  const relativeDir = path.relative(scanDir, dirPath).replace(/\\/g, '/');
+  const directoryName = path.basename(dirPath);
+  const fallbackLabel = kebabToTitleCase(directoryName);
+  const indexEntry = entries.find((entry) => entry.isFile() && /^index\.mdx?$/.test(entry.name));
+  const indexPath = indexEntry ? path.join(dirPath, indexEntry.name) : undefined;
+  const metadata = indexPath
+    ? readNavigationMetadata(indexPath, fallbackLabel)
+    : { title: fallbackLabel, order: undefined };
+  const children: OrderedSidebarItem[] = [];
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      const group = buildDirectorySidebar(fullPath, scanDir);
+      if (group) children.push(group);
+      continue;
+    }
+    if (!entry.isFile() || !/\.mdx?$/.test(entry.name) || /^index\.mdx?$/.test(entry.name)) continue;
+
+    const relativePath = path.relative(scanDir, fullPath).replace(/\\/g, '/');
+    const slug = filePathToSlug(relativePath).replace(/^\/|\/$/g, '');
+    const fallbackTitle = path.basename(entry.name, path.extname(entry.name)).replace(/[-_]/g, ' ');
+    const page = readNavigationMetadata(fullPath, fallbackTitle);
+    children.push({
+      item: { slug },
+      order: page.order,
+      sortLabel: page.title,
+      sortPath: relativePath,
+    });
+  }
+
+  children.sort(compareOrderedSidebarItems);
+  const items: SidebarItem[] = [];
+  if (indexPath) {
+    items.push({
+      label: 'Overview',
+      slug: filePathToSlug(path.relative(scanDir, indexPath)).replace(/^\/|\/$/g, ''),
+      translations: sidebarTranslations.Overview,
+    });
+  }
+  items.push(...children.map((child) => child.item));
+  if (items.length === 0) return undefined;
+
+  const translations = sidebarTranslations[metadata.title as keyof typeof sidebarTranslations];
+  return {
+    item: {
+      label: metadata.title,
+      collapsed: true,
+      ...(translations ? { translations } : {}),
+      items,
+    },
+    order: metadata.order,
+    sortLabel: metadata.title,
+    sortPath: relativeDir,
+  };
+}
+
 /**
  * Convert a file path relative to the content dir into a Starlight link slug.
  * e.g. "resources/api_crawler.md" → "/resources/api_crawler/"
@@ -170,51 +276,46 @@ export function buildSubcategorySidebar(contentDir: string): SidebarItem[] | und
 
   // If no files have subcategory, generate autogenerate entries with translations
   if (!hasAnySubcategory) {
-    const topLevelDirs: string[] = [];
+    let rootEntries: fs.Dirent[];
     try {
-      const dirEntries = fs.readdirSync(scanDir, { withFileTypes: true });
-      for (const entry of dirEntries) {
-        if (entry.isDirectory() && !entry.name.startsWith('.') && !entry.name.startsWith('_')) {
-          topLevelDirs.push(entry.name);
-        }
-      }
+      rootEntries = fs.readdirSync(scanDir, { withFileTypes: true });
     } catch {
       return undefined;
     }
-    if (topLevelDirs.length === 0) return undefined;
+    const orderedItems: OrderedSidebarItem[] = [];
 
-    const sidebar: SidebarItem[] = [];
+    for (const entry of rootEntries) {
+      if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+      const fullPath = path.join(scanDir, entry.name);
 
-    if (hasOverview) {
-      sidebar.push({ label: 'Overview', link: '/', translations: sidebarTranslations.Overview });
+      if (entry.isDirectory()) {
+        const group = buildDirectorySidebar(fullPath, scanDir);
+        if (group) orderedItems.push(group);
+        continue;
+      }
+      if (!entry.isFile() || !/\.mdx?$/.test(entry.name) || /^index\.mdx?$/.test(entry.name)) continue;
+
+      const slug = filePathToSlug(entry.name).replace(/^\/|\/$/g, '');
+      const fallbackTitle = path.basename(entry.name, path.extname(entry.name)).replace(/[-_]/g, ' ');
+      const page = readNavigationMetadata(fullPath, fallbackTitle);
+      orderedItems.push({ item: { slug }, order: page.order, sortLabel: page.title, sortPath: entry.name });
     }
 
-    for (const dir of topLevelDirs.sort()) {
-      const label = kebabToTitleCase(dir);
-      const translations = sidebarTranslations[label as keyof typeof sidebarTranslations];
-      const dirPath = path.join(scanDir, dir);
-      const dirFiles = collectMarkdownFiles(dirPath);
-      const links: SidebarLink[] = dirFiles
-        .map((filePath) => {
-          const relativePath = path.relative(scanDir, filePath).replace(/\\/g, '/');
-          const slug = filePathToSlug(relativePath);
-          const baseName = path.basename(relativePath, path.extname(relativePath));
-          if (baseName === 'index') return null;
-          return { slug: slug.replace(/^\/|\/$/g, '') } as SidebarLink;
-        })
-        .filter((item): item is SidebarLink => item !== null);
-
-      if (links.length > 0) {
-        sidebar.push({
-          label,
-          collapsed: false,
-          ...(translations ? { translations } : {}),
-          items: links,
-        });
-      }
+    if (hasOverview) {
+      const overviewEntry = rootEntries.find((entry) => entry.isFile() && /^index\.mdx?$/.test(entry.name));
+      const overview = overviewEntry
+        ? readNavigationMetadata(path.join(scanDir, overviewEntry.name), 'Overview')
+        : { title: 'Overview', order: undefined };
+      orderedItems.push({
+        item: { label: 'Overview', link: '/', translations: sidebarTranslations.Overview },
+        order: overview.order ?? Number.NEGATIVE_INFINITY,
+        sortLabel: overview.title,
+        sortPath: '',
+      });
     }
 
-    return sidebar;
+    orderedItems.sort(compareOrderedSidebarItems);
+    return orderedItems.length > 0 ? orderedItems.map((entry) => entry.item) : undefined;
   }
 
   // Partition docs by type