@f5-sales-demo/docs-theme 4.4.8 → 4.4.10

package/canonical-route-middleware.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 import type { ProviderPage } from './src/utils/canonical-provider.ts';
-import { collectionNavigation, providerSections } from './src/utils/canonical-provider.ts';
+import { collectionNavigation } from './src/utils/canonical-provider.ts';
+import { stagedProviderSections } from './src/utils/provider-sections.ts';
 
 let providerNavigation: { collections: Record<string, ProviderPage[]> };
 export const onRequest = defineRouteMiddleware(async (context, next) => {
@@ -12,7 +13,7 @@ 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 sections = providerSections.map((section) => ({
+    const sections = stagedProviderSections().map((section) => ({
       type: 'link' as const,
       label: section.label,
       href: `${base.replace(/\/$/, '')}/${section.path}/`,

package/components/ProviderReference.astro

@@ -1,6 +1,9 @@
 ---
 import { CardGrid } from '@astrojs/starlight/components';
-import { providerSections } from '../src/utils/canonical-provider';
+import { stagedProviderSections } from '../src/utils/provider-sections';
+
+const providerSections = stagedProviderSections();
+
 import LinkCard from './LinkCard.astro';
 
 const { entry } = Astro.locals.starlightRoute;

package/config.ts

@@ -32,6 +32,8 @@ import {
 import { sidebarTranslations } from './src/i18n/translations.ts';
 import remarkMermaid from './src/plugins/remark-mermaid.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 { resolveMegaMenuIcon } from './src/utils/resolve-icon.ts';
 import providerSharedAssets from './src/utils/share-provider-assets.mjs';
 import { buildSubcategorySidebar } from './src/utils/subcategory-sidebar.ts';
@@ -669,7 +671,7 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
   }
   const site = options.site || process.env.DOCS_SITE || 'https://f5-sales-demo.github.io';
   const base = options.base || process.env.DOCS_BASE || '/';
-  const title = options.title || process.env.DOCS_TITLE || 'Documentation';
+  const title = options.title || process.env.DOCS_TITLE || (canonicalProvider ? 'Terraform Provider' : 'Documentation');
   const description = options.description || process.env.DOCS_DESCRIPTION || '';
   const githubRepository = options.githubRepository || process.env.GITHUB_REPOSITORY || '';
   let llmsOptionalLinks: Array<{ title: string; url: string }> = options.llmsOptionalLinks || [];
@@ -712,7 +714,11 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
       console.warn('[docs-theme] OPENAPI_SPECS_CONFIG contains invalid JSON; skipping OpenAPI plugin.', e);
     }
   }
-  const megaMenuItems = options.megaMenuItems || (canonicalProvider ? providerMegaMenu(base) : defaultMegaMenuItems);
+  const megaMenuItems =
+    options.megaMenuItems ||
+    (canonicalProvider
+      ? [...defaultMegaMenuItems, ...providerMegaMenu(base, stagedProviderSections(canonicalProvider.manifest))]
+      : defaultMegaMenuItems);
   const head = options.head || (canonicalProvider ? [] : defaultHead);
   const logo = options.logo || { src: '@f5-sales-demo/docs-theme/assets/f5-distributed-cloud.svg' };
   const additionalRemarkPlugins = options.additionalRemarkPlugins || [];
@@ -869,13 +875,17 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
   return defineConfig({
     site,
     base,
+    vite: { plugins: [menuLocalizationPolicy()], ...(canonicalProvider ? { build: { assetsInlineLimit: 0 } } : {}) },
     ...(canonicalProvider
       ? {
           experimental: { collectionStorage: { type: 'chunked' as const, chunkSize: 1024 * 1024 } },
-          vite: { build: { assetsInlineLimit: 0 } },
         }
       : {}),
-    ...(resolvedLocales ? { redirects: { '/': `${normalizedBase}/${resolvedDefaultLocale}/` } } : {}),
+    ...(canonicalProvider
+      ? { redirects: { '/en/': `${normalizedBase}/` } }
+      : resolvedLocales
+        ? { redirects: { '/': `${normalizedBase}/${resolvedDefaultLocale}/` } }
+        : {}),
     markdown: {
       processor: unified({
         remarkPlugins: [remarkMermaid, [codeImport, { allowImportingFromOutside: true }], ...additionalRemarkPlugins],

package/index.ts

@@ -26,7 +26,6 @@ export default function f5xcDocsTheme(): StarlightPlugin {
             ...config.components,
             ...(process.env.DOCS_PROFILE === 'canonical-provider'
               ? {
-                  Header: '@f5-sales-demo/docs-theme/components/ProviderHeader.astro',
                   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.8",
+  "version": "4.4.10",
   "description": "F5 Distributed Cloud branded Starlight documentation theme",
   "type": "module",
   "engines": {

package/src/utils/availability.test.ts

@@ -0,0 +1,25 @@
+import { expect, it } from 'vitest';
+import { availableProviderSections } from './canonical-provider';
+
+it('omits missing historical setup while retaining existing type families', () => {
+  const paths = [
+    'documentation/resources/demo/index.md',
+    'documentation/data-sources/demo/index.md',
+    'documentation/actions/demo/index.md',
+    'documentation/ephemeral-resources/demo/index.md',
+    'documentation/guides/example/index.md',
+  ];
+  expect(availableProviderSections(paths).map((section) => section.path)).toEqual([
+    'guides',
+    'resources',
+    'data-sources',
+    'actions',
+    'ephemeral-resources',
+  ]);
+  expect(availableProviderSections([...paths, 'documentation/provider/setup/index.md'])[0].path).toBe('provider/setup');
+});
+it('does not infer setup from a different provider page or an unrelated folder', () => {
+  expect(
+    availableProviderSections(['documentation/provider/index.md', 'documentation/resources-other/example.md']),
+  ).toEqual([]);
+});

package/src/utils/canonical-provider.ts

@@ -8,6 +8,23 @@ export const providerSections = [
   { label: 'Ephemeral resources', path: 'ephemeral-resources', icon: 'random' },
 ];
 
+export function availableProviderSections(paths: string[]) {
+  const slugs = paths
+    .filter((path) => path.startsWith('documentation/') && /\.mdx?$/.test(path))
+    .map((path) =>
+      path
+        .slice('documentation/'.length)
+        .replace(/(^|\/)index\.mdx?$/, '')
+        .replace(/\.mdx?$/, '')
+        .replace(/\/$/, ''),
+    );
+  return providerSections.filter((section) =>
+    section.path === 'provider/setup'
+      ? slugs.includes(section.path)
+      : slugs.some((slug) => slug === section.path || slug.startsWith(`${section.path}/`)),
+  );
+}
+
 export interface ProviderPage {
   id: string;
   collection_id: string;
@@ -54,7 +71,7 @@ export function collectionNavigation(pages: ProviderPage[], collection: string,
   return (children.get(null) || []).map((page) => tree(page));
 }
 
-export function providerMegaMenu(base: string) {
+export function providerMegaMenu(base: string, sections = providerSections) {
   return [
     {
       label: 'Provider documentation',
@@ -64,7 +81,7 @@ export function providerMegaMenu(base: string) {
         categories: [
           {
             title: 'Terraform xcsh',
-            items: providerSections.map((section) => ({
+            items: sections.map((section) => ({
               label: section.label,
               href: `${base.replace(/\/$/, '')}/${section.path}/`,
             })),

package/src/utils/menu-localization.test.ts

@@ -0,0 +1,15 @@
+import { expect, it } from 'vitest';
+import { menuLocalizationPolicy } from './menu-localization';
+
+it('routes archived desktop and mobile menu localization through the theme policy', () => {
+  const plugin = menuLocalizationPolicy();
+  for (const name of ['MegaMenu.tsx', 'MegaMenuMobile.tsx']) {
+    expect(
+      plugin.resolveId(
+        '../libs/localize-ecosystem-href.ts',
+        `/app/node_modules/@f5-sales-demo/starlight-mega-menu/components/${name}`,
+      ),
+    ).toMatch(/localize-ecosystem-href\.ts$/);
+  }
+  expect(plugin.resolveId('../libs/localize-ecosystem-href.ts', '/app/other.ts')).toBeUndefined();
+});

package/src/utils/menu-localization.ts

@@ -0,0 +1,16 @@
+import { fileURLToPath } from 'node:url';
+
+// The archived menu package has a separate localizer that blindly adds language
+// paths. Route both its desktop and mobile components through the theme policy.
+export function menuLocalizationPolicy() {
+  return {
+    name: 'f5-menu-localization-policy',
+    enforce: 'pre' as const,
+    resolveId(source: string, importer?: string) {
+      if (importer?.includes('/starlight-mega-menu/') && /(?:^|\/)localize-ecosystem-href(?:\.ts)?$/.test(source)) {
+        return fileURLToPath(new URL('./localize-ecosystem-href.ts', import.meta.url));
+      }
+      return undefined;
+    },
+  };
+}

package/src/utils/provider-sections.ts

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import { availableProviderSections } from './canonical-provider.ts';
+
+const sectionsByManifest = new Map<string, ReturnType<typeof availableProviderSections>>();
+export function stagedProviderSections(manifest = process.env.CANONICAL_MANIFEST || '') {
+  if (!manifest) throw new Error('Canonical provider navigation requires a manifest');
+  let sections = sectionsByManifest.get(manifest);
+  if (!sections) {
+    const data = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    if (!data.files || typeof data.files !== 'object' || Array.isArray(data.files)) {
+      throw new Error('Canonical provider manifest requires file receipts');
+    }
+    sections = availableProviderSections(Object.keys(data.files));
+    sectionsByManifest.set(manifest, sections);
+  }
+  return sections;
+}