@f5-sales-demo/docs-theme 4.11.3 → 4.11.5

package/package.json

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

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

@@ -119,3 +119,79 @@ describe('buildSubcategorySidebar without subcategories', () => {
     ]);
   });
 });
+
+describe('authored sidebar metadata', () => {
+  async function fixture(docs: Record<string, string>) {
+    const root = await mkdtemp(path.join(tmpdir(), 'docs-theme-metadata-'));
+    workspaces.push(root);
+    for (const [file, metadata] of Object.entries(docs)) {
+      const destination = path.join(root, file);
+      await mkdir(path.dirname(destination), { recursive: true });
+      await writeFile(destination, `---\ntitle: Article title\n${metadata}\n---\nContent.\n`);
+    }
+    return buildSubcategorySidebar(root);
+  }
+
+  it('uses authored root and nested index labels without Overview translations', async () => {
+    const sidebar = await fixture({
+      'index.mdx': 'sidebar:\n  label: Home\n  order: 0',
+      'plugins/index.mdx': 'sidebar:\n  label: Plugin catalog\n  order: 1',
+      'plugins/tool.mdx': 'sidebar:\n  label: Review documents',
+    });
+    expect(sidebar).toEqual([
+      { label: 'Home', link: '/' },
+      {
+        label: 'Plugin catalog',
+        collapsed: true,
+        items: [
+          { label: 'Plugin catalog', slug: 'plugins' },
+          { label: 'Review documents', slug: 'plugins/tool' },
+        ],
+      },
+    ]);
+  });
+
+  it('omits hidden root and nested pages while keeping children of hidden indexes', async () => {
+    const sidebar = await fixture({
+      'index.mdx': 'sidebar:\n  hidden: true',
+      'hidden.mdx': 'sidebar:\n  hidden: true',
+      'plugins/index.mdx': 'sidebar:\n  label: Plugins\n  hidden: true',
+      'plugins/hidden.mdx': 'sidebar:\n  hidden: true',
+      'plugins/deep/index.mdx': 'sidebar:\n  hidden: true',
+      'plugins/deep/visible.mdx': '',
+      'empty/index.mdx': 'sidebar:\n  hidden: true',
+    });
+    expect(sidebar).toEqual([
+      {
+        label: 'Plugins',
+        collapsed: true,
+        translations: expect.any(Object),
+        items: [{ label: 'Article title', collapsed: true, items: [{ slug: 'plugins/deep/visible' }] }],
+      },
+    ]);
+  });
+
+  it('honors explicit order and alphabetic fallback independently of filenames', async () => {
+    const sidebar = await fixture({
+      'index.mdx': 'sidebar:\n  label: Home\n  order: 2',
+      'last.mdx': 'sidebar:\n  label: First\n  order: 1',
+      'alpha.mdx': 'sidebar:\n  label: Zebra',
+      'zebra.mdx': 'sidebar:\n  label: Alpha',
+    });
+    expect(sidebar).toEqual([
+      { label: 'First', slug: 'last' },
+      { label: 'Home', link: '/' },
+      { label: 'Alpha', slug: 'zebra' },
+      { label: 'Zebra', slug: 'alpha' },
+    ]);
+  });
+
+  it('ignores blank labels and nonboolean hidden values', async () => {
+    const sidebar = await fixture({
+      'index.mdx': 'sidebar:\n  label: " "\n  hidden: "true"',
+      'page.mdx': 'sidebar:\n  label: " "\n  hidden: false',
+    });
+    expect(sidebar?.[0]).toMatchObject({ label: 'Overview', link: '/', translations: expect.any(Object) });
+    expect(sidebar?.[1]).toEqual({ slug: 'page' });
+  });
+});

package/src/utils/subcategory-sidebar.ts

@@ -84,7 +84,14 @@ function kebabToTitleCase(kebab: string): string {
     .join(' ');
 }
 
-function readNavigationMetadata(filePath: string, fallbackTitle: string): { title: string; order: number | undefined } {
+interface NavigationMetadata {
+  title: string;
+  label?: string;
+  hidden: boolean;
+  order: number | undefined;
+}
+
+function readNavigationMetadata(filePath: string, fallbackTitle: string): NavigationMetadata {
   try {
     const raw = fs.readFileSync(filePath, 'utf-8');
     const frontmatter = matter(raw).data as Record<string, unknown>;
@@ -103,15 +110,24 @@ function readNavigationMetadata(filePath: string, fallbackTitle: string): { titl
       Number.isFinite(sidebar.order)
         ? sidebar.order
         : undefined;
-    return { title, order };
+    const label =
+      typeof sidebar === 'object' &&
+      sidebar !== null &&
+      'label' in sidebar &&
+      typeof sidebar.label === 'string' &&
+      sidebar.label.trim()
+        ? sidebar.label.trim()
+        : undefined;
+    const hidden = typeof sidebar === 'object' && sidebar !== null && 'hidden' in sidebar && sidebar.hidden === true;
+    return { title, label, hidden, order };
   } catch {
-    return { title: fallbackTitle, order: undefined };
+    return { title: fallbackTitle, hidden: false, 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;
+  if (!Number.isNaN(orderDifference) && orderDifference !== 0) return orderDifference;
   const labelDifference = a.sortLabel.localeCompare(b.sortLabel);
   return labelDifference !== 0 ? labelDifference : a.sortPath.localeCompare(b.sortPath);
 }
@@ -131,7 +147,7 @@ function buildDirectorySidebar(dirPath: string, scanDir: string): OrderedSidebar
   const indexPath = indexEntry ? path.join(dirPath, indexEntry.name) : undefined;
   const metadata = indexPath
     ? readNavigationMetadata(indexPath, fallbackLabel)
-    : { title: fallbackLabel, order: undefined };
+    : { title: fallbackLabel, hidden: false, order: undefined };
   const children: OrderedSidebarItem[] = [];
 
   for (const entry of entries) {
@@ -149,36 +165,38 @@ function buildDirectorySidebar(dirPath: string, scanDir: string): OrderedSidebar
     const slug = filePathToSlug(relativePath).replace(/^\/|\/$/g, '');
     const fallbackTitle = path.basename(entry.name, path.extname(entry.name)).replace(/[-_]/g, ' ');
     const page = readNavigationMetadata(fullPath, fallbackTitle);
+    if (page.hidden) continue;
     children.push({
-      item: { slug },
+      item: { slug, ...(page.label ? { label: page.label } : {}) },
       order: page.order,
-      sortLabel: page.title,
+      sortLabel: page.label ?? page.title,
       sortPath: relativePath,
     });
   }
 
   children.sort(compareOrderedSidebarItems);
   const items: SidebarItem[] = [];
-  if (indexPath) {
+  if (indexPath && !metadata.hidden) {
     items.push({
-      label: 'Overview',
+      label: metadata.label ?? 'Overview',
       slug: filePathToSlug(path.relative(scanDir, indexPath)).replace(/^\/|\/$/g, ''),
-      translations: sidebarTranslations.Overview,
+      ...(!metadata.label ? { 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];
+  const groupLabel = metadata.label ?? metadata.title;
+  const translations = sidebarTranslations[groupLabel as keyof typeof sidebarTranslations];
   return {
     item: {
-      label: metadata.title,
+      label: groupLabel,
       collapsed: true,
       ...(translations ? { translations } : {}),
       items,
     },
     order: metadata.order,
-    sortLabel: metadata.title,
+    sortLabel: groupLabel,
     sortPath: relativeDir,
   };
 }
@@ -225,6 +243,7 @@ export function buildSubcategorySidebar(contentDir: string): SidebarItem[] | und
   const docs: DocEntry[] = [];
   let hasAnySubcategory = false;
   let hasOverview = false;
+  let overviewMetadata: NavigationMetadata = { title: 'Overview', hidden: false, order: undefined };
 
   for (const filePath of files) {
     const relativePath = path.relative(scanDir, filePath).replace(/\\/g, '/');
@@ -232,7 +251,8 @@ export function buildSubcategorySidebar(contentDir: string): SidebarItem[] | und
 
     // Track overview page separately
     if (slug === '/') {
-      hasOverview = true;
+      overviewMetadata = readNavigationMetadata(filePath, 'Overview');
+      hasOverview = !overviewMetadata.hidden;
       continue;
     }
 
@@ -262,7 +282,9 @@ export function buildSubcategorySidebar(contentDir: string): SidebarItem[] | und
     } else {
       title = path.basename(filePath, path.extname(filePath)).replace(/[-_]/g, ' ');
     }
-    title = cleanPageTitle(title, docType);
+    const navigation = readNavigationMetadata(filePath, title);
+    if (navigation.hidden) continue;
+    title = navigation.label ?? cleanPageTitle(title, docType);
 
     const subcategory =
       typeof frontmatter.subcategory === 'string' && frontmatter.subcategory.trim()
@@ -298,18 +320,25 @@ export function buildSubcategorySidebar(contentDir: string): SidebarItem[] | und
       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 });
+      if (page.hidden) continue;
+      orderedItems.push({
+        item: { slug, ...(page.label ? { label: page.label } : {}) },
+        order: page.order,
+        sortLabel: page.label ?? page.title,
+        sortPath: entry.name,
+      });
     }
 
     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 };
+      const overview = overviewMetadata;
       orderedItems.push({
-        item: { label: 'Overview', link: '/', translations: sidebarTranslations.Overview },
+        item: {
+          label: overview.label ?? 'Overview',
+          link: '/',
+          ...(!overview.label ? { translations: sidebarTranslations.Overview } : {}),
+        },
         order: overview.order ?? Number.NEGATIVE_INFINITY,
-        sortLabel: overview.title,
+        sortLabel: overview.label ?? overview.title,
         sortPath: '',
       });
     }
@@ -332,7 +361,11 @@ export function buildSubcategorySidebar(contentDir: string): SidebarItem[] | und
 
   // 1. Overview link
   if (hasOverview) {
-    sidebar.push({ label: 'Overview', link: '/', translations: sidebarTranslations.Overview });
+    sidebar.push({
+      label: overviewMetadata.label ?? 'Overview',
+      link: '/',
+      ...(!overviewMetadata.label ? { translations: sidebarTranslations.Overview } : {}),
+    });
   }
 
   // 2. Guides group