@f5-sales-demo/docs-theme 3.9.0

package/src/i18n/translator.ts

@@ -0,0 +1,120 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { getGlossary } from './glossary.ts';
+import { buildTranslationPrompt } from './prompt.ts';
+
+export interface TranslateOptions {
+  apiKey: string;
+  model?: string;
+  contentDir: string;
+  force?: boolean;
+}
+
+export function computeSourceHash(content: string): string {
+  return createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
+export function needsTranslation(englishContent: string, targetPath: string): boolean {
+  if (!fs.existsSync(targetPath)) return true;
+
+  const targetRaw = fs.readFileSync(targetPath, 'utf-8');
+  const { data: targetFrontmatter } = matter(targetRaw);
+
+  if (targetFrontmatter.i18n?.translator !== 'machine') {
+    return false;
+  }
+
+  const currentHash = computeSourceHash(englishContent);
+  return targetFrontmatter.i18n.sourceHash !== currentHash;
+}
+
+export async function translateFile(
+  englishPath: string,
+  localeCode: string,
+  localeName: string,
+  options: TranslateOptions,
+): Promise<string | null> {
+  const englishRaw = fs.readFileSync(englishPath, 'utf-8');
+  const { data: frontmatter } = matter(englishRaw);
+
+  const relativePath = path.relative(path.join(options.contentDir, 'en'), englishPath);
+  const targetPath = path.join(options.contentDir, localeCode, relativePath);
+
+  if (!options.force && !needsTranslation(englishRaw, targetPath)) {
+    return null;
+  }
+
+  const { default: Anthropic } = await import('@anthropic-ai/sdk');
+  const client = new Anthropic({ apiKey: options.apiKey });
+
+  const glossary = getGlossary(localeCode);
+  const systemPrompt = buildTranslationPrompt(localeName, localeCode, glossary);
+  const sourceLength = englishRaw.length;
+
+  let translated: string;
+  let attempts = 0;
+  const maxAttempts = 3;
+
+  while (true) {
+    attempts++;
+    try {
+      const stream = client.messages.stream({
+        model: options.model || process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-6',
+        max_tokens: Math.max(4096, Math.ceil(sourceLength * 2.5)),
+        system: systemPrompt,
+        messages: [{ role: 'user', content: englishRaw }],
+      });
+      const response = await stream.finalMessage();
+
+      const textBlock = response.content.find((b) => b.type === 'text');
+      if (textBlock?.type !== 'text') {
+        throw new Error('No text block in API response');
+      }
+      translated = textBlock.text;
+      break;
+    } catch (err: unknown) {
+      const error = err as Error & { status?: number };
+      if (error.status === 429 && attempts < maxAttempts) {
+        const delay = 2 ** attempts * 1000;
+        await new Promise((r) => setTimeout(r, delay));
+        continue;
+      }
+      console.warn(`[translate] Failed to translate ${relativePath} to ${localeCode}: ${error.message}`);
+      return null;
+    }
+  }
+
+  const { data: translatedFrontmatter, content: translatedBody } = matter(translated);
+  const sourceHash = computeSourceHash(englishRaw);
+
+  const mergedFrontmatter = { ...frontmatter };
+  if (translatedFrontmatter.title) mergedFrontmatter.title = translatedFrontmatter.title;
+  if (translatedFrontmatter.description) mergedFrontmatter.description = translatedFrontmatter.description;
+  if (translatedFrontmatter.sidebar?.label) {
+    mergedFrontmatter.sidebar = { ...mergedFrontmatter.sidebar, label: translatedFrontmatter.sidebar.label };
+  }
+  if (translatedFrontmatter.hero) {
+    mergedFrontmatter.hero = { ...mergedFrontmatter.hero };
+    if (translatedFrontmatter.hero.tagline) mergedFrontmatter.hero.tagline = translatedFrontmatter.hero.tagline;
+    if (translatedFrontmatter.hero.title) mergedFrontmatter.hero.title = translatedFrontmatter.hero.title;
+    if (translatedFrontmatter.hero.actions) {
+      mergedFrontmatter.hero.actions = mergedFrontmatter.hero.actions?.map(
+        (action: Record<string, unknown>, i: number) => ({
+          ...action,
+          text: translatedFrontmatter.hero.actions?.[i]?.text || action.text,
+        }),
+      );
+    }
+  }
+
+  mergedFrontmatter.i18n = { sourceHash, translator: 'machine' };
+
+  const output = matter.stringify(translatedBody, mergedFrontmatter);
+
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, output, 'utf-8');
+
+  return targetPath;
+}

package/src/plugins/remark-mermaid.mjs

@@ -0,0 +1,24 @@
+import { visit } from 'unist-util-visit';
+
+export default function remarkMermaid() {
+  return (tree) => {
+    visit(tree, 'code', (node, index, parent) => {
+      if (node.lang !== 'mermaid') return;
+      if (index === undefined || !parent) return;
+
+      const escaped = node.value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+
+      parent.children[index] = {
+        type: 'html',
+        value: `<div class="mermaid-container" data-mermaid-src="${escaped}"><pre class="mermaid">${escaped}</pre></div>`,
+      };
+    });
+
+    // Note: Mermaid CDN script is loaded via Starlight head config in astro.config.mjs.
+    // Script injection via remark HTML nodes is stripped by MDX/Astro for security.
+  };
+}

package/src/types/icon.ts

@@ -0,0 +1,6 @@
+export interface IconSetData {
+  icons: Record<string, { body: string; width?: number; height?: number }>;
+  width?: number;
+  height?: number;
+  info?: { palette?: boolean };
+}

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

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { langToSlug, localizeEcosystemHref } from './localize-ecosystem-href';
+
+describe('langToSlug', () => {
+  it('converts BCP-47 codes with region to lowercase slugs', () => {
+    expect(langToSlug('pt-BR')).toBe('pt-br');
+    expect(langToSlug('zh-CN')).toBe('zh-cn');
+    expect(langToSlug('zh-TW')).toBe('zh-tw');
+  });
+
+  it('passes through simple language codes unchanged', () => {
+    expect(langToSlug('en')).toBe('en');
+    expect(langToSlug('fr')).toBe('fr');
+    expect(langToSlug('ar')).toBe('ar');
+  });
+
+  it('lowercases unknown codes as fallback', () => {
+    expect(langToSlug('sv-SE')).toBe('sv-se');
+  });
+});
+
+describe('localizeEcosystemHref', () => {
+  it('injects locale slug into ecosystem URLs', () => {
+    const result = localizeEcosystemHref('https://f5xc-salesdemos.github.io/waf/', 'fr');
+    expect(result).toBe('https://f5xc-salesdemos.github.io/waf/fr/');
+  });
+
+  it('does not double-inject if locale already present', () => {
+    const result = localizeEcosystemHref('https://f5xc-salesdemos.github.io/waf/fr/', 'fr');
+    expect(result).toBe('https://f5xc-salesdemos.github.io/waf/fr/');
+  });
+
+  it('returns href unchanged for non-ecosystem hosts', () => {
+    const result = localizeEcosystemHref('https://example.com/waf/', 'fr');
+    expect(result).toBe('https://example.com/waf/');
+  });
+
+  it('returns href unchanged for invalid locale slug', () => {
+    const result = localizeEcosystemHref('https://f5xc-salesdemos.github.io/waf/', 'xx-invalid');
+    expect(result).toBe('https://f5xc-salesdemos.github.io/waf/');
+  });
+
+  it('returns href unchanged for empty locale', () => {
+    const result = localizeEcosystemHref('https://f5xc-salesdemos.github.io/waf/', '');
+    expect(result).toBe('https://f5xc-salesdemos.github.io/waf/');
+  });
+
+  it('returns invalid URLs unchanged', () => {
+    const result = localizeEcosystemHref('not-a-url', 'fr');
+    expect(result).toBe('not-a-url');
+  });
+
+  it('works with all 13 supported locale slugs', () => {
+    const slugs = ['en', 'fr', 'es', 'de', 'pt-br', 'ja', 'ko', 'zh-cn', 'zh-tw', 'ar', 'it', 'hi', 'th'];
+    for (const slug of slugs) {
+      const result = localizeEcosystemHref('https://f5xc-salesdemos.github.io/waf/', slug);
+      expect(result).toContain(`/${slug}/`);
+    }
+  });
+
+  it('supports custom ecosystem host', () => {
+    const result = localizeEcosystemHref('https://custom.host.io/waf/', 'fr', 'custom.host.io');
+    expect(result).toBe('https://custom.host.io/waf/fr/');
+  });
+});

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

@@ -0,0 +1,34 @@
+import { bcp47ToSlug, VALID_SLUGS } from '@f5xc-salesdemos/i18n-core';
+
+const ECOSYSTEM_HOST = 'f5xc-salesdemos.github.io';
+
+export const langToSlug = bcp47ToSlug;
+
+export function localizeEcosystemHref(
+  href: string,
+  localeSlug: string,
+  ecosystemHost: string = ECOSYSTEM_HOST,
+): string {
+  if (!localeSlug || !VALID_SLUGS.has(localeSlug)) return href;
+
+  let url: URL;
+  try {
+    url = new URL(href);
+  } catch {
+    return href;
+  }
+
+  if (url.hostname !== ecosystemHost) return href;
+
+  const segments = url.pathname.split('/').filter(Boolean);
+  if (segments.length === 0) return href;
+
+  if (segments.length >= 2 && VALID_SLUGS.has(segments[1])) {
+    return href;
+  }
+
+  segments.splice(1, 0, localeSlug);
+  url.pathname = `/${segments.join('/')}/`;
+
+  return url.toString();
+}

package/src/utils/resolve-icon.ts

@@ -0,0 +1,70 @@
+import { createRequire } from 'node:module';
+import type { IconSetData } from '../types/icon';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Returns true if the SVG body contains explicit color fills (hex, CSS vars,
+ * gradient refs, named colors) — i.e. anything other than "none" or "currentColor".
+ */
+export function hasExplicitColors(body: string): boolean {
+  const fills = body.match(/fill="([^"]*)"/g) || [];
+  return fills.some((f) => f !== 'fill="none"' && f !== 'fill="currentColor"');
+}
+
+/**
+ * Resolves a `prefix:name` icon identifier to a complete SVG string
+ * using the installed Iconify JSON packages. Designed for synchronous
+ * use at module scope (e.g. in config.ts default values).
+ */
+export function resolveIcon(name: string): string {
+  const colonIndex = name.indexOf(':');
+  if (colonIndex === -1) {
+    throw new Error(`Invalid icon name "${name}". Expected "prefix:name" format.`);
+  }
+  const prefix = name.slice(0, colonIndex);
+  const iconName = name.slice(colonIndex + 1);
+
+  let iconData: IconSetData;
+  switch (prefix) {
+    case 'lucide':
+      iconData = require('@iconify-json/lucide/icons.json');
+      break;
+    case 'carbon':
+      iconData = require('@iconify-json/carbon/icons.json');
+      break;
+    case 'mdi':
+      iconData = require('@iconify-json/mdi/icons.json');
+      break;
+    case 'phosphor':
+      iconData = require('@iconify-json/ph/icons.json');
+      break;
+    case 'tabler':
+      iconData = require('@iconify-json/tabler/icons.json');
+      break;
+    case 'f5-brand':
+      iconData = require('@f5xc-salesdemos/icons-f5-brand/icons.json');
+      break;
+    case 'f5xc':
+      iconData = require('@f5xc-salesdemos/icons-f5xc/icons.json');
+      break;
+    case 'hashicorp-flight':
+      iconData = require('@f5xc-salesdemos/icons-hashicorp-flight/icons.json');
+      break;
+    default:
+      throw new Error(
+        `Unknown icon prefix "${prefix}". Available: lucide, carbon, mdi, phosphor, tabler, f5-brand, f5xc, hashicorp-flight`,
+      );
+  }
+
+  const icon = iconData.icons?.[iconName];
+  if (!icon) {
+    throw new Error(`Icon "${iconName}" not found in "${prefix}" icon set.`);
+  }
+
+  const w = icon.width ?? iconData.width ?? 24;
+  const h = icon.height ?? iconData.height ?? 24;
+  const isPalette = iconData.info?.palette === true || hasExplicitColors(icon.body);
+  const fillAttr = isPalette ? '' : ' fill="currentColor"';
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 ${w} ${h}"${fillAttr}>${icon.body}</svg>`;
+}

package/src/utils/subcategory-sidebar.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { filePathToSlug } from './subcategory-sidebar';
+
+describe('filePathToSlug', () => {
+  it('lowercases capitalised path segments to match Starlight entry slugs', () => {
+    // Regression: a capitalised directory (e.g. "Enhancements/") previously
+    // produced a sidebar slug that matched no (lowercased) content entry,
+    // failing the Starlight build with "slug does not exist".
+    expect(filePathToSlug('Enhancements/healthcheck-enhancements.mdx')).toBe('/enhancements/healthcheck-enhancements/');
+  });
+
+  it('leaves already-lowercase paths unchanged', () => {
+    expect(filePathToSlug('resources/api_crawler.md')).toBe('/resources/api_crawler/');
+    expect(filePathToSlug('guides/getting-started.md')).toBe('/guides/getting-started/');
+  });
+
+  it('maps index files to the root slug', () => {
+    expect(filePathToSlug('index.md')).toBe('/');
+    expect(filePathToSlug('section/index.mdx')).toBe('/section/');
+  });
+
+  it('normalises backslashes to forward slashes', () => {
+    expect(filePathToSlug('Enhancements\\foo.mdx')).toBe('/enhancements/foo/');
+  });
+});

package/src/utils/subcategory-sidebar.ts

@@ -0,0 +1,316 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { sidebarTranslations } from '../i18n/translations.ts';
+
+/**
+ * Starlight sidebar config types (simplified).
+ */
+type SidebarLink = { label: string; link?: string; slug?: string; translations?: Record<string, string> };
+type SidebarGroup = { label: string; items: SidebarItem[]; collapsed?: boolean; translations?: Record<string, string> };
+type SidebarItem = SidebarLink | SidebarGroup;
+
+type DocType = 'resource' | 'data-source' | 'guide' | 'function';
+
+interface DocEntry {
+  title: string;
+  subcategory: string | undefined;
+  docType: DocType;
+  slug: string;
+}
+
+/**
+ * Detect the doc type from a file path relative to the content directory.
+ * Matches the first path segment against known prefixes.
+ */
+function detectDocType(relativePath: string): DocType | undefined {
+  const normalized = relativePath.replace(/\\/g, '/');
+  if (normalized.startsWith('resources/')) return 'resource';
+  if (normalized.startsWith('data-sources/')) return 'data-source';
+  if (normalized.startsWith('guides/')) return 'guide';
+  if (normalized.startsWith('functions/')) return 'function';
+  return undefined;
+}
+
+/**
+ * Recursively collect all .md and .mdx files under a directory.
+ */
+function collectMarkdownFiles(dir: string): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectMarkdownFiles(fullPath));
+    } else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Clean a page_title to match Terraform Registry sidebar labels.
+ * Resources:    "f5xc_http_loadbalancer Resource - terraform-provider-f5xc" → "f5xc_http_loadbalancer"
+ * Data Sources: "f5xc_http_loadbalancer Data Source - terraform-provider-f5xc" → "f5xc_http_loadbalancer"
+ * Functions:    "blindfold function - terraform-provider-f5xc" → "blindfold"
+ * Guides:       "Guide: HTTP Load Balancer with Security Features" → "HTTP Load Balancer with Security Features"
+ */
+function cleanPageTitle(pageTitle: string, docType: DocType): string {
+  if (docType === 'guide') {
+    return pageTitle.replace(/^Guide:\s*/i, '').trim();
+  }
+  if (docType === 'function') {
+    return pageTitle.replace(/\s+function\s*-\s*.*$/i, '').trim();
+  }
+  return pageTitle.replace(/\s+(Resource|Data Source)\s*-\s*.*$/i, '').trim();
+}
+
+const KNOWN_ACRONYMS = new Set(['api', 'faq', 'dns', 'cli', 'sdk', 'ui', 'ip', 'mcp', 'tui']);
+
+function kebabToTitleCase(kebab: string): string {
+  return kebab
+    .split('-')
+    .map((word) => (KNOWN_ACRONYMS.has(word) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1)))
+    .join(' ');
+}
+
+/**
+ * Convert a file path relative to the content dir into a Starlight link slug.
+ * e.g. "resources/api_crawler.md" → "/resources/api_crawler/"
+ *      "guides/getting-started.md" → "/guides/getting-started/"
+ *      "index.md" → "/"
+ */
+export function filePathToSlug(relativePath: string): string {
+  const normalized = relativePath
+    .replace(/\\/g, '/')
+    .replace(/\.mdx?$/, '')
+    .replace(/\/index$/, '')
+    // Starlight lowercases content-entry slugs, so the sidebar slug must be
+    // lowercased too — otherwise a capitalised path segment (e.g. "Enhancements/")
+    // produces a sidebar slug that matches no entry and fails the build.
+    .toLowerCase();
+
+  if (normalized === 'index' || normalized === '') return '/';
+  return `/${normalized}/`;
+}
+
+/**
+ * Scan the content directory for .md/.mdx files, parse frontmatter,
+ * and build a Starlight sidebar config grouped by subcategory.
+ *
+ * Returns `undefined` if no files contain a `subcategory` field,
+ * letting Starlight fall back to directory-based auto-generation.
+ */
+export function buildSubcategorySidebar(contentDir: string): SidebarItem[] | undefined {
+  const resolvedDir = path.resolve(contentDir);
+  if (!fs.existsSync(resolvedDir)) {
+    console.warn(`[subcategory-sidebar] Content directory not found: ${resolvedDir}`);
+    return undefined;
+  }
+
+  // If an "en" subdirectory exists, scan it instead (locale-aware content structure)
+  const enDir = path.join(resolvedDir, 'en');
+  const scanDir = fs.existsSync(enDir) ? enDir : resolvedDir;
+
+  const files = collectMarkdownFiles(scanDir);
+  const docs: DocEntry[] = [];
+  let hasAnySubcategory = false;
+  let hasOverview = false;
+
+  for (const filePath of files) {
+    const relativePath = path.relative(scanDir, filePath).replace(/\\/g, '/');
+    const slug = filePathToSlug(relativePath);
+
+    // Track overview page separately
+    if (slug === '/') {
+      hasOverview = true;
+      continue;
+    }
+
+    // Skip index pages — they serve as section headers, not content
+    const baseName = path.basename(relativePath, path.extname(relativePath));
+    if (baseName === 'index') continue;
+
+    const docType = detectDocType(relativePath);
+    if (!docType) continue; // skip files not in a recognized directory
+
+    let frontmatter: Record<string, unknown>;
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const parsed = matter(raw);
+      frontmatter = parsed.data;
+    } catch {
+      continue; // skip unparseable files
+    }
+
+    // Determine title from page_title (or title after entrypoint.sh renames it),
+    // then clean it to match Terraform Registry sidebar label format.
+    let title = '';
+    if (typeof frontmatter.title === 'string' && frontmatter.title.trim()) {
+      title = frontmatter.title.trim();
+    } else if (typeof frontmatter.page_title === 'string' && frontmatter.page_title.trim()) {
+      title = frontmatter.page_title.trim();
+    } else {
+      title = path.basename(filePath, path.extname(filePath)).replace(/[-_]/g, ' ');
+    }
+    title = cleanPageTitle(title, docType);
+
+    const subcategory =
+      typeof frontmatter.subcategory === 'string' && frontmatter.subcategory.trim()
+        ? frontmatter.subcategory.trim()
+        : undefined;
+
+    if (subcategory) hasAnySubcategory = true;
+
+    docs.push({ title, subcategory, docType, slug });
+  }
+
+  // If no files have subcategory, generate autogenerate entries with translations
+  if (!hasAnySubcategory) {
+    const topLevelDirs: string[] = [];
+    try {
+      const dirEntries = fs.readdirSync(scanDir, { withFileTypes: true });
+      for (const entry of dirEntries) {
+        if (entry.isDirectory() && !entry.name.startsWith('.') && !entry.name.startsWith('_')) {
+          topLevelDirs.push(entry.name);
+        }
+      }
+    } catch {
+      return undefined;
+    }
+    if (topLevelDirs.length === 0) return undefined;
+
+    const sidebar: SidebarItem[] = [];
+
+    if (hasOverview) {
+      sidebar.push({ label: 'Overview', link: '/', translations: sidebarTranslations.Overview });
+    }
+
+    for (const dir of topLevelDirs.sort()) {
+      const label = kebabToTitleCase(dir);
+      const translations = sidebarTranslations[label as keyof typeof sidebarTranslations];
+      const dirPath = path.join(scanDir, dir);
+      const dirFiles = collectMarkdownFiles(dirPath);
+      const links: SidebarLink[] = dirFiles
+        .map((filePath) => {
+          const relativePath = path.relative(scanDir, filePath).replace(/\\/g, '/');
+          const slug = filePathToSlug(relativePath);
+          const baseName = path.basename(relativePath, path.extname(relativePath));
+          if (baseName === 'index') return null;
+          return { slug: slug.replace(/^\/|\/$/g, '') } as SidebarLink;
+        })
+        .filter((item): item is SidebarLink => item !== null);
+
+      if (links.length > 0) {
+        sidebar.push({
+          label,
+          collapsed: false,
+          ...(translations ? { translations } : {}),
+          items: links,
+        });
+      }
+    }
+
+    return sidebar;
+  }
+
+  // Partition docs by type
+  const guides = docs.filter((d) => d.docType === 'guide');
+  const functions = docs.filter((d) => d.docType === 'function');
+  const resources = docs.filter((d) => d.docType === 'resource');
+  const dataSources = docs.filter((d) => d.docType === 'data-source');
+
+  // Alphabetical sort helper
+  const byTitle = (a: DocEntry, b: DocEntry) => a.title.localeCompare(b.title);
+
+  // Build sidebar
+  const sidebar: SidebarItem[] = [];
+
+  // 1. Overview link
+  if (hasOverview) {
+    sidebar.push({ label: 'Overview', link: '/', translations: sidebarTranslations.Overview });
+  }
+
+  // 2. Guides group
+  if (guides.length > 0) {
+    sidebar.push({
+      label: 'Guides',
+      collapsed: true,
+      translations: sidebarTranslations.Guides,
+      items: guides.sort(byTitle).map((g) => ({ slug: g.slug.replace(/^\/|\/$/g, '') })),
+    });
+  }
+
+  // 3. Functions group
+  if (functions.length > 0) {
+    sidebar.push({
+      label: 'Functions',
+      collapsed: true,
+      translations: sidebarTranslations.Functions,
+      items: functions.sort(byTitle).map((f) => ({ slug: f.slug.replace(/^\/|\/$/g, '') })),
+    });
+  }
+
+  // 4. Subcategory groups (resources + data sources)
+  const subcategoryMap = new Map<string, { resources: DocEntry[]; dataSources: DocEntry[] }>();
+
+  for (const doc of [...resources, ...dataSources]) {
+    const cat = doc.subcategory ?? 'Uncategorized';
+    let bucket = subcategoryMap.get(cat);
+    if (!bucket) {
+      bucket = { resources: [], dataSources: [] };
+      subcategoryMap.set(cat, bucket);
+    }
+    if (doc.docType === 'resource') {
+      bucket.resources.push(doc);
+    } else {
+      bucket.dataSources.push(doc);
+    }
+  }
+
+  // Sort subcategories alphabetically, but push "Uncategorized" to the end
+  const sortedCategories = [...subcategoryMap.keys()].sort((a, b) => {
+    if (a === 'Uncategorized') return 1;
+    if (b === 'Uncategorized') return -1;
+    return a.localeCompare(b);
+  });
+
+  for (const category of sortedCategories) {
+    const entry = subcategoryMap.get(category);
+    if (!entry) continue;
+    const { resources: catResources, dataSources: catDataSources } = entry;
+    const groupItems: SidebarItem[] = [];
+
+    if (catResources.length > 0) {
+      groupItems.push({
+        label: 'Resources',
+        translations: sidebarTranslations.Resources,
+        items: catResources.sort(byTitle).map((r) => ({ slug: r.slug.replace(/^\/|\/$/g, '') })),
+      });
+    }
+
+    if (catDataSources.length > 0) {
+      groupItems.push({
+        label: 'Data Sources',
+        translations: sidebarTranslations['Data Sources'],
+        items: catDataSources.sort(byTitle).map((d) => ({ slug: d.slug.replace(/^\/|\/$/g, '') })),
+      });
+    }
+
+    if (groupItems.length > 0) {
+      sidebar.push({
+        label: category,
+        collapsed: true,
+        ...(sidebarTranslations[category as keyof typeof sidebarTranslations]
+          ? { translations: sidebarTranslations[category as keyof typeof sidebarTranslations] }
+          : {}),
+        items: groupItems,
+      });
+    }
+  }
+
+  return sidebar;
+}