@f5-sales-demo/docs-theme 4.7.1 → 4.9.0

package/components/CanadaSidebar.astro

@@ -0,0 +1,77 @@
+---
+import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
+import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
+import SidebarRestorePoint from '@astrojs/starlight/components/SidebarRestorePoint.astro';
+
+const { sidebar } = Astro.locals.starlightRoute;
+---
+
+<SidebarPersister>
+  <ul class="canada-sidebar">
+    {sidebar.map((entry) => {
+      if (entry.type === 'link') {
+        return <li><a class="home-link" href={entry.href} aria-current={entry.isCurrent ? 'page' : undefined}>{entry.label}</a></li>;
+      }
+
+      const [overview, ...children] = entry.entries;
+      if (!overview || overview.type !== 'link') {
+        return <li><SidebarSublist sublist={[entry]} /></li>;
+      }
+      const active = overview.isCurrent || children.some((child) => child.type === 'link' && child.isCurrent);
+
+      return <li class="stage">
+        <a class="stage-link" href={overview.href} aria-current={overview.isCurrent ? 'page' : undefined}>{entry.label}</a>
+        <details open={active || !entry.collapsed}>
+          <summary aria-label={`Toggle ${entry.label} pages`} title={`Toggle ${entry.label} pages`}><span class="caret" aria-hidden="true"></span></summary>
+          <SidebarRestorePoint />
+          <SidebarSublist sublist={children} nested />
+        </details>
+      </li>;
+    })}
+  </ul>
+</SidebarPersister>
+
+<div class="md:sl-hidden"><MobileMenuFooter /></div>
+
+<style>
+  @layer starlight.core {
+    .canada-sidebar { list-style: none; margin: 0; padding: 0; }
+    .canada-sidebar > li + li { margin-top: 0.5rem; }
+    .stage { position: relative; }
+    .home-link, .stage-link {
+      display: block;
+      border-radius: 0.25rem;
+      color: var(--sl-color-gray-2);
+      line-height: 1.4;
+      padding: 0.3em 2.5rem 0.3em 0.5rem;
+      text-decoration: none;
+      font-size: var(--sl-text-sm);
+    }
+    .stage-link { color: var(--sl-color-white); font-weight: 600; }
+    .home-link:hover, .home-link:focus, .stage-link:hover, .stage-link:focus { color: var(--sl-color-white); }
+    a[aria-current='page'], a[aria-current='page']:hover, a[aria-current='page']:focus {
+      color: var(--sl-color-text-invert);
+      background-color: var(--sl-color-text-accent);
+      font-weight: 600;
+    }
+    summary {
+      position: absolute;
+      inset-block-start: 0;
+      inset-inline-end: 0;
+      display: grid;
+      place-items: center;
+      width: 2rem;
+      height: 2rem;
+      cursor: pointer;
+      border-radius: 0.25rem;
+      list-style: none;
+    }
+    summary::-webkit-details-marker { display: none; }
+    summary:hover, summary:focus-visible { color: var(--sl-color-white); background: var(--sl-color-gray-5); }
+    .caret { width: 0.55rem; height: 0.55rem; border-block-start: 2px solid currentColor; border-inline-end: 2px solid currentColor; transform: rotate(45deg); transition: transform 0.2s ease; }
+    details[open] .caret { transform: rotate(135deg); }
+    :global([dir='rtl']) .caret { transform: rotate(225deg); }
+    :global([dir='rtl']) details[open] .caret { transform: rotate(135deg); }
+  }
+</style>

package/config.ts

@@ -35,7 +35,7 @@ import canonicalLlms from './src/utils/canonical-llms.mjs';
 import { providerMegaMenu } from './src/utils/canonical-provider.ts';
 import { menuLocalizationPolicy } from './src/utils/menu-localization.ts';
 import { stagedProviderSections } from './src/utils/provider-sections.ts';
-import { repositoryPublicationProfile } from './src/utils/publication-profiles.ts';
+import { publicationSidebar, repositoryPublicationProfile } from './src/utils/publication-profiles.ts';
 import { resolveMegaMenuIcon } from './src/utils/resolve-icon.ts';
 import providerSharedAssets from './src/utils/share-provider-assets.mjs';
 import { buildSubcategorySidebar } from './src/utils/subcategory-sidebar.ts';
@@ -782,7 +782,7 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
     starlightMegaMenu({ items: megaMenuItems, mobileLabels }),
     starlightVideosPlugin(),
     starlightImageZoom(),
-    f5xcDocsTheme(),
+    f5xcDocsTheme(githubRepository),
     starlightScrollToTop({
       showTooltip: true,
       tooltipText: {
@@ -843,7 +843,9 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
   ];
 
   const contentDir = process.env.CONTENT_DIR || 'src/content/docs';
-  const subcategorySidebar = canonicalProvider ? [] : buildSubcategorySidebar(contentDir);
+  const subcategorySidebar = canonicalProvider
+    ? []
+    : publicationSidebar(githubRepository, buildSubcategorySidebar(contentDir));
 
   // Auto-detect i18n: enable locales only when content has an en/ subdirectory.
   // Repos that haven't migrated to docs/en/ won't get a broken language selector.

package/index.ts

@@ -1,7 +1,7 @@
 import type { StarlightPlugin } from '@astrojs/starlight/types';
 import { translations } from './src/i18n/translations.ts';
 
-export default function f5xcDocsTheme(): StarlightPlugin {
+export default function f5xcDocsTheme(repository = process.env.GITHUB_REPOSITORY || ''): StarlightPlugin {
   return {
     name: '@f5-sales-demo/docs-theme',
     hooks: {
@@ -29,7 +29,11 @@ export default function f5xcDocsTheme(): StarlightPlugin {
               ? {
                   Sidebar: '@f5-sales-demo/docs-theme/components/ProviderSidebar.astro',
                 }
-              : {}),
+              : repository === 'f5-sales-demo/canada'
+                ? {
+                    Sidebar: '@f5-sales-demo/docs-theme/components/CanadaSidebar.astro',
+                  }
+                : {}),
             Banner: '@f5-sales-demo/docs-theme/components/Banner.astro',
             EditLink: '@f5-sales-demo/docs-theme/components/EditLink.astro',
             Footer: '@f5-sales-demo/docs-theme/components/Footer.astro',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f5-sales-demo/docs-theme",
-  "version": "4.7.1",
+  "version": "4.9.0",
   "description": "F5 Distributed Cloud branded Starlight documentation theme",
   "type": "module",
   "engines": {
@@ -43,6 +43,7 @@
     "./src/utils/localize-ecosystem-href.ts": "./src/utils/localize-ecosystem-href.ts",
     "./canonical-route-middleware": "./canonical-route-middleware.ts",
     "./components/ProviderSidebar.astro": "./components/ProviderSidebar.astro",
+    "./components/CanadaSidebar.astro": "./components/CanadaSidebar.astro",
     "./components/ProviderHeader.astro": "./components/ProviderHeader.astro",
     "./components/SharedHeader.astro": "./components/SharedHeader.astro",
     "./assets/canada-flag.svg": "./assets/canada-flag.svg",

package/src/utils/canada-sidebar-plugin.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+import f5xcDocsTheme from '../../index';
+
+function configuredComponents(repository: string) {
+  const updateConfig = vi.fn();
+  const setup = f5xcDocsTheme(repository).hooks?.['config:setup'];
+  if (!setup) throw new Error('theme setup hook is missing');
+  setup({
+    config: { components: {} },
+    updateConfig,
+    addRouteMiddleware: vi.fn(),
+    logger: { info: vi.fn() },
+  } as never);
+  return updateConfig.mock.calls[0][0].components;
+}
+
+describe('Canada-only sidebar override', () => {
+  it('selects the linked stage sidebar for Canada', () => {
+    expect(configuredComponents('f5-sales-demo/canada').Sidebar).toBe(
+      '@f5-sales-demo/docs-theme/components/CanadaSidebar.astro',
+    );
+  });
+
+  it('leaves other repositories on their existing sidebar', () => {
+    expect(configuredComponents('f5-sales-demo/multi-cloud-networking')).not.toHaveProperty('Sidebar');
+  });
+});

package/src/utils/publication-profiles.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it } from 'vitest';
 import { localizeEcosystemHref } from './localize-ecosystem-href';
-import { repositoryPublicationProfile } from './publication-profiles';
+import { publicationSidebar, repositoryPublicationProfile } from './publication-profiles';
 
 describe('Canadian publication', () => {
   it('publishes only English and selects the flag favicon', () => {
-    expect(repositoryPublicationProfile('f5-sales-demo/canada')).toEqual({
+    expect(repositoryPublicationProfile('f5-sales-demo/canada')).toMatchObject({
       locales: { en: { label: 'English', lang: 'en' } },
       defaultLocale: 'en',
       favicon: '/assets/canada-favicon.svg',
@@ -17,3 +17,43 @@ describe('Canadian publication', () => {
     );
   });
 });
+
+describe('publication profile sidebar', () => {
+  it('orders four linked stages and covers all 14 pages once', () => {
+    const sidebar = publicationSidebar('f5-sales-demo/canada', []);
+    expect(sidebar?.[0]).toEqual({ slug: 'index' });
+    const stages = sidebar?.slice(1) ?? [];
+    expect(stages.map((stage) => ('label' in stage ? stage.label : ''))).toEqual([
+      'Design',
+      'Deploy',
+      'Verify',
+      'Operate',
+    ]);
+    const expected = [
+      ['design', 'use-case', 'architecture'],
+      ['deploy', 'deployment', 'terraform'],
+      ['verify', 'presentation', 'verification'],
+      ['operate', 'troubleshooting', 'failover', 'teardown'],
+    ];
+    const routes = ['index'];
+    stages.forEach((stage, index) => {
+      expect(stage).toMatchObject({ collapsed: true });
+      if (!('items' in stage)) throw new Error('Canada stage must have items');
+      const stageRoutes = stage.items.map((item) => {
+        if (!('slug' in item)) throw new Error('Canada stage item must be a page');
+        return item.slug;
+      });
+      expect(stageRoutes).toEqual(expected[index]);
+      routes.push(...stageRoutes);
+    });
+    expect(new Set(routes).size).toBe(14);
+    expect(routes).toHaveLength(14);
+    expect(stages.every((stage) => 'label' in stage && stage.label.split(/\s+/).length <= 3)).toBe(true);
+  });
+  it('preserves fallback navigation for every repository without a sidebar profile', () => {
+    const fallback = [{ label: 'Existing', slug: 'en/existing' }];
+    expect(publicationSidebar('f5-sales-demo/multi-cloud-networking', fallback)).toBe(fallback);
+    expect(publicationSidebar('f5-sales-demo/docs-theme', undefined)).toBeUndefined();
+    expect(publicationSidebar('f5-sales-demo/canada', fallback)).not.toBe(fallback);
+  });
+});

package/src/utils/publication-profiles.ts

@@ -1,15 +1,51 @@
+import type starlight from '@astrojs/starlight';
+
+type Sidebar = NonNullable<Parameters<typeof starlight>[0]['sidebar']>;
+
+interface PublicationProfile {
+  locales: Record<string, { label: string; lang: string }>;
+  defaultLocale: string;
+  favicon: string;
+  sidebar?: Sidebar;
+}
+
 /** Repository publication decisions shared by navigation and site configuration. */
-export const publicationProfiles: Record<
-  string,
-  { locales: Record<string, { label: string; lang: string }>; defaultLocale: string; favicon: string }
-> = {
+export const publicationProfiles: Record<string, PublicationProfile> = {
   canada: {
     locales: { en: { label: 'English', lang: 'en' } },
     defaultLocale: 'en',
     favicon: '/assets/canada-favicon.svg',
+    sidebar: [
+      { slug: 'index' },
+      {
+        label: 'Design',
+        collapsed: true,
+        items: [{ slug: 'design' }, { slug: 'use-case' }, { slug: 'architecture' }],
+      },
+      {
+        label: 'Deploy',
+        collapsed: true,
+        items: [{ slug: 'deploy' }, { slug: 'deployment' }, { slug: 'terraform' }],
+      },
+      {
+        label: 'Verify',
+        collapsed: true,
+        items: [{ slug: 'verify' }, { slug: 'presentation' }, { slug: 'verification' }],
+      },
+      {
+        label: 'Operate',
+        collapsed: true,
+        items: [{ slug: 'operate' }, { slug: 'troubleshooting' }, { slug: 'failover' }, { slug: 'teardown' }],
+      },
+    ],
   },
 };
 
 export function repositoryPublicationProfile(repository: string) {
   return publicationProfiles[repository.split('/').pop() || ''];
 }
+
+/** Preserve automatic navigation unless this repository explicitly supplies a sidebar. */
+export function publicationSidebar(repository: string, fallback: Sidebar | undefined) {
+  return repositoryPublicationProfile(repository)?.sidebar ?? fallback;
+}