@f5-sales-demo/docs-theme 4.3.15 → 4.4.1

package/canonical-route-middleware.ts

@@ -0,0 +1,40 @@
+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';
+
+let providerNavigation: { collections: Record<string, ProviderPage[]> };
+export const onRequest = defineRouteMiddleware(async (context, next) => {
+  const route = context.locals.starlightRoute;
+  const entry = route.entry;
+  const canonical = process.env.DOCS_PROFILE === 'canonical-provider';
+  if (canonical) {
+    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) => ({
+      type: 'link' as const,
+      label: section.label,
+      href: `${base.replace(/\/$/, '')}/${section.path}/`,
+      isCurrent: route.id === section.path,
+      badge: undefined,
+      attrs: {},
+    }));
+    route.sidebar = [
+      ...sections,
+      ...(metadata
+        ? collectionNavigation(
+            providerNavigation.collections[metadata.collection_id] || [],
+            metadata.collection_id,
+            base,
+            route.id,
+          )
+        : []),
+    ];
+    route.hasSidebar = true;
+    route.pagination = { prev: undefined, next: undefined };
+    route.siteTitleHref = base;
+  }
+
+  await next();
+});

package/components/MarkdownContent.astro

@@ -1,7 +1,13 @@
 ---
+import ProviderReference from './ProviderReference.astro';
+
+const canonical = process.env.DOCS_PROFILE === 'canonical-provider';
+
 import ImageZoom from 'starlight-image-zoom/components/ImageZoom.astro';
 import StarlightVideosMarkdownContent from 'starlight-videos/components/MarkdownContent.astro';
 ---
 
 <ImageZoom />
-<StarlightVideosMarkdownContent><slot /></StarlightVideosMarkdownContent>
+<StarlightVideosMarkdownContent>
+  {canonical ? <ProviderReference><slot /></ProviderReference> : <slot />}
+</StarlightVideosMarkdownContent>

package/components/ProviderReference.astro

@@ -0,0 +1,55 @@
+---
+import { CardGrid } from '@astrojs/starlight/components';
+import { providerSections } from '../src/utils/canonical-provider';
+import LinkCard from './LinkCard.astro';
+
+const { entry } = Astro.locals.starlightRoute;
+const metadata = entry.data.xcsh_docs;
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+---
+{!metadata && (entry.id === 'index' || entry.id === '') && <CardGrid>
+  {providerSections.map(section => <LinkCard title={section.label} href={`${base}/${section.path}/`} />)}
+</CardGrid>}
+<label class="version-control">Documentation version
+  <select id="provider-version" aria-label="Documentation version"><option>{process.env.DOCUMENTATION_LABEL || 'Latest stable'}</option></select>
+</label>
+<slot />
+{metadata && <footer class="provider-provenance">
+  <p>Schema path: <code>{metadata.schema_path.join('.') || 'root'}</code> · <a href={metadata.source_url}>Complete Markdown</a></p>
+  <small>{metadata.id} · {metadata.body_sha256}</small>
+</footer>}
+<style>
+.provider-provenance { border-top: 1px solid var(--sl-color-gray-5); margin-top: 2rem; padding-top: 1rem; overflow-wrap: anywhere; }
+.provider-provenance p { margin-bottom: .5rem; }
+.provider-provenance small { color: var(--sl-color-gray-3); }
+</style>
+
+<script>
+  const select = document.querySelector<HTMLSelectElement>('#provider-version');
+  const publicationRoot = '/terraform-provider-xcsh/';
+  if (select) {
+    fetch(`${publicationRoot}documentation-versions.json`).then(response => response.json()).then(data => {
+      const path = window.location.pathname.slice(publicationRoot.length);
+      const prefix = path.startsWith('versions/') ? path.split('/').slice(0, 2).join('/') + '/' : path.startsWith('preview/main/') ? 'preview/main/' : '';
+      const equivalent = path.slice(prefix.length);
+      const versions = [{ label: `Latest stable (${data.latest})`, prefix: '' }, ...data.versions.map((version: string) => ({ label: version, prefix: `versions/${version}/` })), { label: 'Main preview', prefix: 'preview/main/' }];
+      select.replaceChildren(...versions.map(version => {
+        const option = document.createElement('option');
+        option.textContent = version.label;
+        option.value = version.prefix;
+        option.selected = prefix === version.prefix;
+        return option;
+      }));
+      select.addEventListener('change', async () => {
+        const landing = `${publicationRoot}${select.value}`;
+        const destination = `${landing}${equivalent}`;
+        const response = await fetch(destination, { method: 'HEAD' });
+        window.location.assign(response.ok ? destination : landing);
+      });
+    }).catch(() => { select.disabled = true; });
+  }
+</script>
+<style>
+.version-control { display: flex; gap: .5rem; flex-wrap: wrap; margin-bottom: 1rem; font-size: var(--sl-text-sm); }
+select { max-width: 100%; padding: .25rem; }
+</style>

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 { providerMegaMenu } from './src/utils/canonical-provider.ts';
 import { resolveMegaMenuIcon } from './src/utils/resolve-icon.ts';
 import { buildSubcategorySidebar } from './src/utils/subcategory-sidebar.ts';
 
@@ -100,6 +101,7 @@ interface HeadEntry {
 }
 
 export interface F5xcDocsConfigOptions {
+  canonicalProvider?: { contentRoot: string; manifest: string; navigation: string; version: string };
   site?: string;
   base?: string;
   title?: string;
@@ -651,6 +653,19 @@ export const federatedSearchSites = [
 ];
 
 export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
+  const canonicalProvider =
+    options.canonicalProvider ||
+    (process.env.DOCS_PROFILE === 'canonical-provider'
+      ? {
+          contentRoot: process.env.CONTENT_DIR || 'src/content/docs',
+          manifest: process.env.CANONICAL_MANIFEST || '',
+          navigation: process.env.PROVIDER_NAVIGATION || '',
+          version: process.env.DOCUMENTATION_LABEL || 'Latest stable',
+        }
+      : undefined);
+  if (canonicalProvider && (!canonicalProvider.manifest || !canonicalProvider.navigation)) {
+    throw new Error('[docs-theme] canonical-provider requires manifest and navigation');
+  }
   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';
@@ -696,13 +711,13 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
       console.warn('[docs-theme] OPENAPI_SPECS_CONFIG contains invalid JSON; skipping OpenAPI plugin.', e);
     }
   }
-  const megaMenuItems = options.megaMenuItems || defaultMegaMenuItems;
+  const megaMenuItems = options.megaMenuItems || (canonicalProvider ? providerMegaMenu(base) : defaultMegaMenuItems);
   const head = options.head || defaultHead;
   const logo = options.logo || { src: '@f5-sales-demo/docs-theme/assets/f5-distributed-cloud.svg' };
   const additionalRemarkPlugins = options.additionalRemarkPlugins || [];
   const additionalIntegrations = options.additionalIntegrations || [];
 
-  const federatedSearch = options.federatedSearch !== false;
+  const federatedSearch = !canonicalProvider && options.federatedSearch !== false;
   const normalizedBase = base.replace(/\/+$/, '');
   const repositoryCorpusPolicy = progressiveCorpusPolicy(llmsConfig);
   const progressiveCorpus =
@@ -776,29 +791,35 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
           ),
         ]
       : []),
-    starlightLlmsTxt({
-      projectName: title,
-      description,
-      rawContent: false,
-      optionalLinks: llmsOptionalLinks,
-      sidebarNav: true,
-      tieredHierarchy: true,
-      promote: llmsConfig.promote || ['index*', 'overview*'],
-      demote: llmsConfig.demote || ['references*'],
-      ...(llmsFederatedSites.length > 0 ? { federatedSites: llmsFederatedSites } : {}),
-      ...(llmsFederatedSiteCategories.length > 0 ? { federatedSiteCategories: llmsFederatedSiteCategories } : {}),
-      ...(progressiveCorpus ? { progressiveCorpus } : {}),
-    }),
+    ...(!canonicalProvider
+      ? [
+          starlightLlmsTxt({
+            projectName: title,
+            description,
+            rawContent: false,
+            optionalLinks: llmsOptionalLinks,
+            sidebarNav: true,
+            tieredHierarchy: true,
+            promote: llmsConfig.promote || ['index*', 'overview*'],
+            demote: llmsConfig.demote || ['references*'],
+            ...(llmsFederatedSites.length > 0 ? { federatedSites: llmsFederatedSites } : {}),
+            ...(llmsFederatedSiteCategories.length > 0 ? { federatedSiteCategories: llmsFederatedSiteCategories } : {}),
+            ...(progressiveCorpus ? { progressiveCorpus } : {}),
+          }),
+        ]
+      : []),
   ];
 
   const contentDir = process.env.CONTENT_DIR || 'src/content/docs';
-  const subcategorySidebar = buildSubcategorySidebar(contentDir);
+  const subcategorySidebar = canonicalProvider ? [] : 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.
   const hasEnSubdir = fs.existsSync(path.resolve(contentDir, 'en'));
   const resolvedLocales =
-    options.locales === false ? undefined : options.locales || (hasEnSubdir ? f5xcDefaultLocales : undefined);
+    canonicalProvider || options.locales === false
+      ? undefined
+      : options.locales || (hasEnSubdir ? f5xcDefaultLocales : undefined);
   const resolvedDefaultLocale = options.defaultLocale || f5xcDefaultLocale;
 
   const localeHeadScripts: HeadEntry[] = [];
@@ -848,6 +869,9 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
   return defineConfig({
     site,
     base,
+    ...(canonicalProvider
+      ? { experimental: { collectionStorage: { type: 'chunked' as const, chunkSize: 1024 * 1024 } } }
+      : {}),
     ...(resolvedLocales ? { redirects: { '/': `${normalizedBase}/${resolvedDefaultLocale}/` } } : {}),
     markdown: {
       processor: unified({

package/index.ts

@@ -10,8 +10,11 @@ export default function f5xcDocsTheme(): StarlightPlugin {
       },
       'config:setup'({ config, updateConfig, addRouteMiddleware, logger }) {
         addRouteMiddleware({
-          entrypoint: '@f5-sales-demo/docs-theme/route-middleware',
-          order: 'pre',
+          entrypoint:
+            process.env.DOCS_PROFILE === 'canonical-provider'
+              ? '@f5-sales-demo/docs-theme/canonical-route-middleware'
+              : '@f5-sales-demo/docs-theme/route-middleware',
+          order: process.env.DOCS_PROFILE === 'canonical-provider' ? 'post' : 'pre',
         });
         updateConfig({
           customCss: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f5-sales-demo/docs-theme",
-  "version": "4.3.15",
+  "version": "4.4.1",
   "description": "F5 Distributed Cloud branded Starlight documentation theme",
   "type": "module",
   "engines": {
@@ -40,7 +40,8 @@
     "./src/i18n/locales.ts": "./src/i18n/locales.ts",
     "./src/i18n/translator.ts": "./src/i18n/translator.ts",
     "./src/i18n/prompt.ts": "./src/i18n/prompt.ts",
-    "./src/utils/localize-ecosystem-href.ts": "./src/utils/localize-ecosystem-href.ts"
+    "./src/utils/localize-ecosystem-href.ts": "./src/utils/localize-ecosystem-href.ts",
+    "./canonical-route-middleware": "./canonical-route-middleware.ts"
   },
   "files": [
     "index.ts",
@@ -52,7 +53,8 @@
     "styles/",
     "assets/",
     "components/",
-    "src/"
+    "src/",
+    "canonical-route-middleware.ts"
   ],
   "keywords": [
     "starlight",
@@ -70,7 +72,7 @@
   },
   "devDependencies": {
     "@astrojs/markdown-remark": "^7.2.4",
-    "@astrojs/starlight": "^0.41.9",
+    "@astrojs/starlight": "0.41.9",
     "@f5-sales-demo/icons-f5-brand": "^0.2.0",
     "@f5-sales-demo/icons-f5xc": "^0.3.2",
     "@f5-sales-demo/icons-hashicorp-flight": "^0.3.0",
@@ -82,7 +84,7 @@
     "@playwright/test": "^1.62.1",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.7",
-    "astro": "^7.2.8",
+    "astro": "7.2.8",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "vitest": "^4.1.11"

package/route-middleware.ts

@@ -1,6 +1,7 @@
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 import { itemLabels, menuLabels } from './src/i18n/mega-menu-translations.ts';
+import { isCanonicalReference } from './src/utils/canonical-provider.ts';
 
 const titleTranslations: Record<string, Record<string, string>> = { ...menuLabels, ...itemLabels };
 
@@ -55,7 +56,7 @@ export const onRequest = defineRouteMiddleware(async (context, next) => {
   const route = context.locals.starlightRoute;
   const entry = route.entry;
 
-  if (isIndexPage(entry.filePath)) {
+  if (!isCanonicalReference(entry.data) && isIndexPage(entry.filePath)) {
     // Unconditionally hide TOC on index pages
     route.toc = undefined;
   }

package/src/content.config.ts

@@ -5,6 +5,24 @@ import { docsSchema } from '@astrojs/starlight/schema';
 export const collections = {
   docs: defineCollection({
     loader: docsLoader(),
-    schema: docsSchema({ extend: z.object({ subcategory: z.string().optional() }) }),
+    schema: docsSchema({
+      extend: z.object({
+        subcategory: z.string().optional(),
+        xcsh_docs: z
+          .object({
+            id: z.string(),
+            collection_id: z.string(),
+            role: z.string(),
+            parent_id: z.string().nullable(),
+            child_ids: z.array(z.string()),
+            schema_path: z.array(z.string()),
+            provider_type: z.string(),
+            body_sha256: z.string(),
+            source_url: z.string().optional(),
+          })
+          .passthrough()
+          .optional(),
+      }),
+    }),
   }),
 };

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { collectionNavigation, isCanonicalReference, providerSections } from './canonical-provider';
+
+describe('canonical provider navigation', () => {
+  it('includes all four provider families and setup and guides', () => {
+    expect(providerSections.map((s) => s.path)).toEqual([
+      'provider/setup',
+      'guides',
+      'resources',
+      'data-sources',
+      'actions',
+      'ephemeral-resources',
+    ]);
+  });
+  it('retains canonical index navigation and TOC', () => {
+    expect(isCanonicalReference({ xcsh_docs: { role: 'reference' } })).toBe(true);
+    expect(isCanonicalReference({})).toBe(false);
+  });
+  it('includes only the active collection, with parent relationships', () => {
+    const pages = [
+      { id: 'a', collection_id: 'one', parent_id: null, title: 'One', slug: 'resources/one' },
+      { id: 'b', collection_id: 'one', parent_id: 'a', title: 'Property', slug: 'resources/one/properties' },
+      { id: 'c', collection_id: 'two', parent_id: null, title: 'Two', slug: 'resources/two' },
+    ];
+    const nav = collectionNavigation(pages, 'one', '/version/', 'resources/one/properties');
+    expect(JSON.stringify(nav)).not.toContain('Two');
+    expect(nav[0].entries[1].href).toBe('/version/resources/one/properties/');
+    expect(nav[0].entries[1].isCurrent).toBe(true);
+  });
+});
+
+describe('bounded collection expansion', () => {
+  it('keeps sibling references and expands only the exact active ancestry', () => {
+    const pages = [
+      { id: 'root', collection_id: 'c', parent_id: null, title: 'Root', slug: 'resources/demo' },
+      { id: 'a', collection_id: 'c', parent_id: 'root', title: 'A', slug: 'resources/demo/properties/a' },
+      { id: 'aa', collection_id: 'c', parent_id: 'a', title: 'AA', slug: 'resources/demo/properties/a/child' },
+      { id: 'b', collection_id: 'c', parent_id: 'root', title: 'B', slug: 'resources/demo/properties/ab' },
+      { id: 'bb', collection_id: 'c', parent_id: 'b', title: 'BB', slug: 'resources/demo/properties/ab/child' },
+    ];
+    const nav = collectionNavigation(pages, 'c', '/', 'resources/demo/properties/a/child');
+    const text = JSON.stringify(nav);
+    expect(text).toContain('AA');
+    expect(text).toContain('"label":"B"');
+    expect(text).not.toContain('BB');
+    expect(nav[0].type).toBe('group');
+  });
+});

package/src/utils/canonical-provider.ts

@@ -0,0 +1,76 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+export const providerSections = [
+  { label: 'Setup', path: 'provider/setup', icon: 'seti:terraform' },
+  { label: 'Guides', path: 'guides', icon: 'open-book' },
+  { label: 'Resources', path: 'resources', icon: 'puzzle' },
+  { label: 'Data sources', path: 'data-sources', icon: 'document' },
+  { label: 'Actions', path: 'actions', icon: 'rocket' },
+  { label: 'Ephemeral resources', path: 'ephemeral-resources', icon: 'random' },
+];
+
+export interface ProviderPage {
+  id: string;
+  collection_id: string;
+  parent_id: string | null;
+  title: string;
+  slug: string;
+}
+
+export function isCanonicalReference(data: { xcsh_docs?: { role?: string } }) {
+  return !!data.xcsh_docs?.role;
+}
+
+export function collectionNavigation(pages: ProviderPage[], collection: string, base: string, current: string) {
+  const active = pages.filter((page) => page.collection_id === collection);
+  const ids = new Set(active.map((page) => page.id));
+  const children = new Map<string | null, ProviderPage[]>();
+  for (const page of active) {
+    const parent = page.parent_id && ids.has(page.parent_id) ? page.parent_id : null;
+    children.set(parent, [...(children.get(parent) || []), page]);
+  }
+  const link = (page: ProviderPage) => ({
+    type: 'link' as const,
+    label: page.title,
+    href: `${base.replace(/\/$/, '')}/${page.slug}/`,
+    isCurrent: page.slug === current,
+    badge: undefined,
+    attrs: {},
+  });
+  const tree = (page: ProviderPage, seen = new Set<string>()): StarlightRouteData['sidebar'][number] => {
+    if (seen.has(page.id)) throw new Error(`Cyclic canonical navigation: ${page.id}`);
+    const descendants = children.get(page.id) || [];
+    // Other branches remain navigable through their reference page, whose
+    // content lists every direct child. Expand only the active ancestry.
+    if (!descendants.length || !(current === page.slug || current.startsWith(`${page.slug}/`))) return link(page);
+    const next = new Set([...seen, page.id]);
+    return {
+      type: 'group',
+      label: page.title,
+      collapsed: !current.startsWith(page.slug),
+      badge: undefined,
+      entries: [link(page), ...descendants.map((child) => tree(child, next))],
+    };
+  };
+  return (children.get(null) || []).map((page) => tree(page));
+}
+
+export function providerMegaMenu(base: string) {
+  return [
+    {
+      label: 'Provider documentation',
+      content: {
+        layout: 'grid' as const,
+        columns: 2 as const,
+        categories: [
+          {
+            title: 'Terraform xcsh',
+            items: providerSections.map((section) => ({
+              label: section.label,
+              href: `${base.replace(/\/$/, '')}/${section.path}/`,
+            })),
+          },
+        ],
+      },
+    },
+  ];
+}