@f5-sales-demo/docs-theme 4.11.4 → 4.11.6

package/index.ts

@@ -25,6 +25,7 @@ export default function f5xcDocsTheme(repository = process.env.GITHUB_REPOSITORY
           components: {
             ...config.components,
             Header: '@f5-sales-demo/docs-theme/components/SharedHeader.astro',
+            Head: '@f5-sales-demo/docs-theme/components/Head.astro',
             ...(process.env.DOCS_PROFILE === 'canonical-provider'
               ? {
                   Sidebar: '@f5-sales-demo/docs-theme/components/ProviderSidebar.astro',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f5-sales-demo/docs-theme",
-  "version": "4.11.4",
+  "version": "4.11.6",
   "description": "F5 Distributed Cloud branded Starlight documentation theme",
   "type": "module",
   "engines": {
@@ -46,6 +46,7 @@
     "./components/CanadaSidebar.astro": "./components/CanadaSidebar.astro",
     "./components/ProviderHeader.astro": "./components/ProviderHeader.astro",
     "./components/SharedHeader.astro": "./components/SharedHeader.astro",
+    "./components/Head.astro": "./components/Head.astro",
     "./assets/canada-flag.svg": "./assets/canada-flag.svg",
     "./assets/canada-favicon.svg": "./assets/canada-favicon.svg"
   },

package/src/utils/localize-ecosystem-href.ts

@@ -29,6 +29,10 @@ export function localizeEcosystemHref(
   const segments = url.pathname.split('/').filter(Boolean);
   if (segments.length === 0) return href;
 
+  // Organization-root routes begin with a locale, not a project slug.
+  // Explicit catalog locale links must never become /en/fr/demos/.
+  if (VALID_SLUGS.has(segments[0])) return href;
+
   if (NON_LOCALIZED_ECOSYSTEM_SLUGS.has(segments[0])) return href;
 
   if (segments.length >= 2 && VALID_SLUGS.has(segments[1])) {

package/src/utils/page-title.test.ts

@@ -0,0 +1,7 @@
+import { expect, it } from 'vitest';
+import { pageTitle } from './page-title';
+
+it('omits a duplicate site suffix while retaining distinct page titles', () => {
+  expect(pageTitle('Sales demos', 'Sales demos', 'Sales demos | Sales demos')).toBe('Sales demos');
+  expect(pageTitle('Demo catalog', 'Sales demos', 'Demo catalog | Sales demos')).toBe('Demo catalog | Sales demos');
+});

package/src/utils/page-title.ts

@@ -0,0 +1,4 @@
+/** Keep the framework title format except when its site suffix repeats the page. */
+export function pageTitle(title: string, siteTitle: string, formattedTitle: string): string {
+  return title === siteTitle ? title : formattedTitle;
+}

package/src/utils/search-sites.ts

@@ -0,0 +1,32 @@
+export const federatedSearchSites = [
+  { repo: 'docs-builder', label: 'Documentation builder' },
+  { repo: 'docs-theme', label: 'Shared documentation theme' },
+  { repo: 'f5-sales-demo.github.io', label: 'Sales demo portal' },
+  { repo: 'administration', label: 'Administration' },
+  { repo: 'nginx', label: 'NGINX One' },
+  { repo: 'observability', label: 'Observability' },
+  { repo: 'statistics', label: 'Statistics' },
+  { repo: 'was', label: 'Web App Scanning' },
+  { repo: 'multi-cloud-networking', label: 'Multi-Cloud Networking' },
+  { repo: 'canada', label: 'Canada topology' },
+  { repo: 'dns', label: 'DNS Management' },
+  { repo: 'cdn', label: 'Content Delivery Network' },
+  { repo: 'bot-standard', label: 'Bot Defense Standard' },
+  { repo: 'bot-advanced', label: 'Bot Defense Advanced' },
+  { repo: 'ddos', label: 'DDoS Mitigation' },
+  { repo: 'webapp-api-protection', label: 'Web App & API Protection' },
+  { repo: 'api-protection', label: 'API Protection' },
+  { repo: 'xcsh', label: 'xcsh' },
+  { repo: 'xcsh-action', label: 'xcsh GitHub Action' },
+  { repo: 'csd', label: 'Client-Side Defense' },
+  { repo: 'docs-icons', label: 'Icon packages' },
+  { repo: 'marketplace', label: 'xcsh marketplace' },
+  { repo: 'api-specs', label: 'API specifications' },
+  { repo: 'api-specs-enriched', label: 'Enriched API specifications' },
+  { repo: 'cdn-simulator', label: 'CDN simulator' },
+  { repo: 'origin-server', label: 'Origin server' },
+  { repo: 'traffic-generator', label: 'Traffic generator' },
+  { repo: 'demo-resources', label: 'Demo resource catalog' },
+  { repo: 'xcsh-chrome-extension', label: 'xcsh Chrome extension' },
+  { repo: 'console', label: 'Console catalog' },
+];

package/src/utils/search-source.test.ts

@@ -0,0 +1,9 @@
+import { expect, it } from 'vitest';
+import { searchSource } from './search-source';
+
+it('identifies the source project of federated results and root catalog pages', () => {
+  const sources = [{ repo: 'origin-server', label: 'Origin server' }];
+  expect(searchSource('https://f5-sales-demo.github.io/origin-server/en/03-deploy/', sources)).toBe('Origin server');
+  expect(searchSource('https://f5-sales-demo.github.io/en/demos/', sources)).toBe('Sales demo portal');
+  expect(searchSource('https://example.com/docs/', sources)).toBeUndefined();
+});

package/src/utils/search-source.ts

@@ -0,0 +1,11 @@
+export function searchSource(href: string, sources: Array<{ repo: string; label: string }>): string | undefined {
+  let url: URL;
+  try {
+    url = new URL(href);
+  } catch {
+    return undefined;
+  }
+  if (url.hostname !== 'f5-sales-demo.github.io') return undefined;
+  const project = url.pathname.split('/').filter(Boolean)[0];
+  return sources.find((source) => source.repo === project)?.label ?? 'Sales demo portal';
+}

package/src/utils/showcase-navigation.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { defaultMegaMenuItems } from '../../config';
+import { localizeEcosystemHref } from './localize-ecosystem-href';
+
+describe('showcase navigation', () => {
+  it('uses the audience taxonomy without duplicate project destinations', () => {
+    expect(defaultMegaMenuItems.map((item) => item.label)).toEqual([
+      'Demos',
+      'Demo environment',
+      'Operations',
+      'Developer tools',
+      'Ecosystem',
+      'F5 services',
+    ]);
+    const links = defaultMegaMenuItems.flatMap((item) => item.content?.categories?.flatMap((c) => c.items) ?? []);
+    const urls = links.map((item) => item.href);
+    expect(new Set(urls).size).toBe(urls.length);
+    expect(urls).not.toContain('https://f5-sales-demo.github.io/');
+    expect(links.find((l) => l.href.includes('/api-protection/'))?.label).toBe('API Protection');
+    expect(links.find((l) => l.href.includes('/ddos/'))?.label).toBe('DDoS Mitigation');
+    expect(defaultMegaMenuItems[1].content?.footer?.label).toBe('Demo resource catalog');
+  });
+
+  it('keeps explicit English catalog destinations valid across locale selection', () => {
+    for (const locale of ['en', 'fr', 'ar']) {
+      expect(localizeEcosystemHref('https://f5-sales-demo.github.io/en/demos/', locale)).toBe(
+        'https://f5-sales-demo.github.io/en/demos/',
+      );
+      expect(localizeEcosystemHref('https://f5-sales-demo.github.io/en/ecosystem/', locale)).toBe(
+        'https://f5-sales-demo.github.io/en/ecosystem/',
+      );
+    }
+  });
+});

package/src/utils/statistics-navigation.test.ts

@@ -4,15 +4,15 @@ import { localizeEcosystemHref } from './localize-ecosystem-href';
 
 describe('Statistics discovery', () => {
   it('lists Statistics beside monitoring tools exactly once', () => {
-    const networking = defaultMegaMenuItems.find((item) => item.label === 'Networking');
-    const category = networking?.content?.categories?.find((item) => item.title === 'Manage & Monitor');
+    const networking = defaultMegaMenuItems.find((item) => item.label === 'Operations');
+    const category = networking?.content?.categories?.find((item) => item.title === 'Queries and administration');
     const statistics = category?.items?.filter((item) => item.label === 'Statistics');
     expect(statistics).toHaveLength(1);
     expect(statistics?.[0]).toMatchObject({
       href: 'https://f5-sales-demo.github.io/statistics/en/',
-      description: 'API metrics, access logs, and security events',
+      description: 'Query access logs, application metrics, and security telemetry through the API.',
     });
-    expect(category?.items?.map((item) => item.label)).toEqual(['Observability', 'Statistics', 'Administration']);
+    expect(category?.items?.map((item) => item.label)).toEqual(['Statistics', 'Observability', 'Administration']);
   });
   it('adds Statistics to federated search and avoids self-index duplication', () => {
     expect(federatedSearchSites.filter((item) => item.repo === 'statistics')).toHaveLength(1);

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

package/styles/custom.css

@@ -873,3 +873,33 @@ summary:focus-visible {
   }
 }
 
+
+/* The sales showcase prioritizes destinations over decorative hero space. */
+body:has(.sales-showcase) .hero {
+  padding-block: 1rem;
+  grid-template-columns: 1fr;
+  gap: 1rem;
+}
+body:has(.sales-showcase) .hero h1 {
+  font-size: clamp(1.75rem, 5vw, 3rem);
+}
+body:has(.sales-showcase) .hero .tagline {
+  max-width: 48rem;
+  font-size: var(--sl-text-lg);
+}
+body:has(.sales-showcase) .hero > .stack { gap: 1rem; }
+body:has(.sales-showcase) .hero .actions { gap: 0.75rem; }
+.sales-showcase { --showcase-gap: 1rem; }
+.sales-showcase .card-grid { gap: var(--showcase-gap); }
+.sales-showcase .sl-link-card { background: var(--sl-color-gray-7, var(--sl-color-gray-6)); }
+.sales-showcase h2 { margin-block-start: 2rem; }
+.sales-showcase h3 { margin-block-start: 1rem; }
+@media (max-width: 49.99rem) {
+  body:has(.sales-showcase) .hero { padding-block: 0.5rem; }
+  body:has(.sales-showcase) .hero .actions { flex-wrap: wrap; }
+}
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { scroll-behavior: auto !important; }
+  .sl-link-card, .smm-viewport, .smm-content { transition: none !important; animation: none !important; }
+  .sl-link-card:hover { transform: none; }
+}