@f5-sales-demo/docs-theme 4.4.11 → 4.5.0

package/canonical-route-middleware.ts

@@ -13,6 +13,17 @@ export const onRequest = defineRouteMiddleware(async (context, next) => {
     providerNavigation ||= JSON.parse(fs.readFileSync(process.env.PROVIDER_NAVIGATION || '', 'utf8'));
     const metadata = entry.data.xcsh_docs;
     const base = import.meta.env.BASE_URL;
+    const slug = route.id.replace(/\/$/, '');
+    const scope = metadata ? slug || '_llms-txt/root' : null;
+    route.head.push({
+      tag: 'link',
+      attrs: {
+        rel: 'describedby',
+        href: scope
+          ? `${base.replace(/\/$/, '')}/${scope}/_llms/content/llms.txt`
+          : `${base.replace(/\/$/, '')}/llms.txt`,
+      },
+    });
     const sections = stagedProviderSections().map((section) => ({
       type: 'link' as const,
       label: section.label,

package/components/SharedHeader.astro

@@ -0,0 +1,122 @@
+---
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import Search from 'virtual:starlight/components/Search';
+import SiteTitle from 'virtual:starlight/components/SiteTitle';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
+import config from 'virtual:starlight/user-config';
+import MegaMenu from './SharedMegaMenu.tsx';
+import MegaMenuMobile from './SharedMegaMenuMobile.tsx';
+
+/**
+ * Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
+ */
+const shouldRenderSearch = config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
+---
+
+<div class="header sl-mega-menu-header">
+	<div class="title-wrapper sl-flex">
+		<SiteTitle />
+	</div>
+	<nav class="smm-desktop-nav">
+		<MegaMenu client:only="react" />
+	</nav>
+	<div class="sl-flex print:hidden">
+		{shouldRenderSearch && <Search />}
+	</div>
+	<div class="sl-hidden md:sl-flex print:hidden right-group">
+		<div class="sl-flex social-icons">
+			<SocialIcons />
+		</div>
+		<ThemeSelect />
+		<LanguageSelect />
+	</div>
+	<div class="smm-mobile-toggle">
+		<MegaMenuMobile client:only="react" />
+	</div>
+</div>
+
+<style>
+	@layer starlight.core {
+		.header {
+			display: flex;
+			gap: var(--sl-nav-gap);
+			justify-content: space-between;
+			align-items: center;
+			height: 100%;
+		}
+
+		.title-wrapper {
+			/* Prevent long titles overflowing and covering the search and menu buttons on narrow viewports. */
+			overflow: clip;
+			/* Avoid clipping focus ring around link inside title wrapper. */
+			padding: 0.25rem;
+			margin: -0.25rem;
+			min-width: 0;
+		}
+
+		.right-group,
+		.social-icons {
+			gap: 1rem;
+			align-items: center;
+		}
+		.social-icons::after {
+			content: '';
+			height: 2rem;
+			border-inline-end: 1px solid var(--sl-color-gray-5);
+		}
+
+		/* Desktop nav is hidden on small screens */
+		.smm-desktop-nav {
+			display: none;
+		}
+
+		/* Mobile toggle is visible on small screens */
+		.smm-mobile-toggle {
+			display: flex;
+			align-items: center;
+		}
+
+		@media (min-width: 50rem) {
+			:global(:root[data-has-sidebar]) {
+				--__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+			}
+			:global(:root:not([data-has-toc])) {
+				--__toc-width: 0rem;
+			}
+			.header {
+				--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
+				--__main-column-fr: calc(
+					(
+							100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
+								(2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
+								var(--sl-content-width)
+						) / 2
+				);
+				display: grid;
+				grid-template-columns:
+					/* 1 (site title) */
+					auto
+					/* 2 (mega-menu nav) */
+					1fr
+					/* 3 (search box) */
+					auto
+					/* 4 (right items) */
+					auto;
+				align-content: center;
+			}
+
+			/* Show desktop nav, hide mobile toggle */
+			.smm-desktop-nav {
+				display: flex;
+				align-items: center;
+				justify-content: center;
+				min-width: 0;
+			}
+
+			.smm-mobile-toggle {
+				display: none;
+			}
+		}
+	}
+</style>

package/components/SharedMegaMenu.tsx

@@ -0,0 +1,5 @@
+import config from 'virtual:starlight-mega-menu/config';
+import MegaMenu from '@f5-sales-demo/starlight-mega-menu/components/MegaMenu.tsx';
+export default function SharedMegaMenu() {
+  return <MegaMenu config={config} />;
+}

package/components/SharedMegaMenuMobile.tsx

@@ -0,0 +1,5 @@
+import config from 'virtual:starlight-mega-menu/config';
+import MegaMenuMobile from '@f5-sales-demo/starlight-mega-menu/components/MegaMenuMobile.tsx';
+export default function SharedMegaMenuMobile() {
+  return <MegaMenuMobile config={config} />;
+}

package/config.ts

@@ -31,6 +31,7 @@ import {
 } from './src/i18n/mega-menu-translations.ts';
 import { sidebarTranslations } from './src/i18n/translations.ts';
 import remarkMermaid from './src/plugins/remark-mermaid.mjs';
+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';
@@ -933,7 +934,9 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
         ],
       }),
       react(),
-      ...(canonicalProvider ? [providerSharedAssets()] : []),
+      ...(canonicalProvider
+        ? [providerSharedAssets(), canonicalLlms({ contentRoot: canonicalProvider.contentRoot, base, title })]
+        : []),
       ...additionalIntegrations,
     ],
   });

package/index.ts

@@ -24,6 +24,7 @@ export default function f5xcDocsTheme(): StarlightPlugin {
           ],
           components: {
             ...config.components,
+            Header: '@f5-sales-demo/docs-theme/components/SharedHeader.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.4.11",
+  "version": "4.5.0",
   "description": "F5 Distributed Cloud branded Starlight documentation theme",
   "type": "module",
   "engines": {
@@ -43,7 +43,8 @@
     "./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/ProviderHeader.astro": "./components/ProviderHeader.astro"
+    "./components/ProviderHeader.astro": "./components/ProviderHeader.astro",
+    "./components/SharedHeader.astro": "./components/SharedHeader.astro"
   },
   "files": [
     "index.ts",
@@ -143,7 +144,7 @@
     "@anthropic-ai/sdk": "^0.121.0",
     "@astrojs/react": "^6.0.4",
     "@f5-sales-demo/i18n-core": "^1.0.56",
-    "@f5-sales-demo/starlight-llms-txt": "2.2.0",
+    "@f5-sales-demo/starlight-llms-txt": "2.3.0",
     "@f5-sales-demo/starlight-mega-menu": "^3.0.0",
     "gray-matter": "^4.0.3",
     "remark-code-import": "^1.2.0",

package/src/utils/canonical-llms.mjs

@@ -0,0 +1,18 @@
+import { fileURLToPath } from 'node:url';
+import { readCanonicalCorpus, writeCanonicalHierarchy } from '@f5-sales-demo/starlight-llms-txt/canonical-corpus';
+
+export default function canonicalLlms({ contentRoot, base, title }) {
+  return {
+    name: 'f5-canonical-llms',
+    hooks: {
+      'astro:config:setup'() {
+        // Validate before Astro starts processing staged content.
+        const corpus = readCanonicalCorpus(contentRoot);
+        if (!corpus.pages.length) throw new Error('Canonical publication has no pages');
+      },
+      'astro:build:done'({ dir }) {
+        writeCanonicalHierarchy({ contentRoot, outputRoot: fileURLToPath(dir), base, title });
+      },
+    },
+  };
+}

package/src/utils/canonical-llms.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const read = vi.fn(() => ({ pages: [{}] }));
+const write = vi.fn();
+vi.mock('@f5-sales-demo/starlight-llms-txt/canonical-corpus', () => ({
+  readCanonicalCorpus: read,
+  writeCanonicalHierarchy: write,
+}));
+describe('canonical llms integration', () => {
+  it('validates the original root before processing and streams after the build', async () => {
+    const { default: integration } = await import('./canonical-llms.mjs');
+    const plugin = integration({ contentRoot: '/fixture/documentation', base: '/preview/', title: 'Fixture' });
+    expect(read).not.toHaveBeenCalled();
+    plugin.hooks['astro:config:setup']();
+    expect(read).toHaveBeenCalledWith('/fixture/documentation');
+    plugin.hooks['astro:build:done']({ dir: new URL('file:///fixture/output/') });
+    expect(write).toHaveBeenCalledWith({
+      contentRoot: '/fixture/documentation',
+      outputRoot: '/fixture/output/',
+      base: '/preview/',
+      title: 'Fixture',
+    });
+  });
+});

package/src/utils/shared-header.test.ts

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+import { expect, it } from 'vitest';
+
+it('bundles menu config in shared clients instead of serialized island props', () => {
+  const header = readFileSync(new URL('../../components/SharedHeader.astro', import.meta.url), 'utf8');
+  expect(header).not.toContain('config={');
+  expect(header).toContain('<ThemeSelect');
+  expect(header).toContain('<LanguageSelect');
+  expect(header).toContain('<SocialIcons');
+  for (const name of ['SharedMegaMenu', 'SharedMegaMenuMobile']) {
+    const client = readFileSync(new URL(`../../components/${name}.tsx`, import.meta.url), 'utf8');
+    expect(client).toContain('virtual:starlight-mega-menu/config');
+  }
+});