refactor: unify configuration management across standards sites

- Replaced individual Docusaurus config files with centralized `docusaurus.config.factory.ts` for modular and consistent setup.
- Added dynamic navbar and footer generation for ISBD, UNIMARC, ISBDM, LRM, and Muldicat using `SiteConfigBuilder`.
- Resolved build-time caching contamination with environment-aware dynamic configuration.
- Standardized introduction docs and removed redundant `DocsEnv` imports.

Author: jonphipps

packages/preset-ifla/src/index.ts

@@ -38,9 +38,7 @@ const preset: IFLAPresetFunction = function (
     projectName = siteKey,
     env,
     vocabularyDefaults,
-    customNavbarItems = [],
-    navigation = {},
-    footer = {},
+    // customNavbarItems, navigation, footer - DEPRECATED: ignored, use docusaurus.config.factory.ts
     editUrl,
     // additionalPlugins = [], // TODO: implement when needed
     // redirects, // TODO: implement when needed  
@@ -64,7 +62,7 @@ const preset: IFLAPresetFunction = function (
   // Merge vocabulary defaults with user overrides
   const mergedVocabularyDefaults = mergeVocabularyDefaults(vocabularyDefaults);
 
-  // Build base theme configuration (no navbar/footer - those are built in individual configs)
+  // Build base theme configuration (no navbar/footer - those are built in individual site configs)
   const themeConfig = buildThemeConfig(
     prismTheme,
     prismDarkTheme,
@@ -182,4 +180,4 @@ export default preset;
 export { getSiteConfig } from './utils';
 
 // Export types for consumer use
-export type { IFLAPresetOptions, IFLANavigationOptions, IFLAFooterOptions } from './types';
+export type { IFLAPresetOptions } from './types';

packages/preset-ifla/src/types.ts

@@ -36,32 +36,8 @@ export interface VocabularyDefaults {
   };
 }
 
-/**
- * Navigation options for the preset
- */
-export interface IFLANavigationOptions {
-  /** Hide the current site from the Standards dropdown */
-  hideCurrentSiteFromStandardsDropdown?: boolean;
-  /** Position of the Standards dropdown in navbar */
-  standardsDropdownPosition?: 'left' | 'right';
-  /** Whether to include the Resources dropdown */
-  includeResourcesDropdown?: boolean;
-  /** Whether to include the Documentation navbar item */
-  includeDocumentationItem?: boolean;
-}
-
-/**
- * Footer customization options
- */
-export interface IFLAFooterOptions {
-  /** Additional resource links to add to the footer */
-  additionalResourceLinks?: Array<{
-    label: string;
-    href: string;
-  }>;
-  /** Hide default resource links (RDF Downloads, Sitemap) for sites that don't have them */
-  hideDefaultResourceLinks?: boolean;
-}
+// NOTE: Navigation and footer options removed - these should be handled 
+// in individual site configs using SiteConfigBuilder to prevent caching contamination
 
 /**
  * Redirect configuration options
@@ -135,14 +111,14 @@ export interface IFLAPresetOptions {
   /** Vocabulary configuration overrides */
   vocabularyDefaults?: Partial<VocabularyDefaults>;
 
-  /** Custom navbar items to add (in addition to standard items) */
+  /** Custom navbar items to add (in addition to standard items) - DEPRECATED: Use docusaurus.config.factory.ts */
   customNavbarItems?: NavbarItem[];
 
-  /** Navigation customization options */
-  navigation?: IFLANavigationOptions;
+  /** Navigation customization options - DEPRECATED: Use docusaurus.config.factory.ts */
+  navigation?: Record<string, any>;
 
-  /** Footer customization options */
-  footer?: IFLAFooterOptions;
+  /** Footer customization options - DEPRECATED: Use docusaurus.config.factory.ts */
+  footer?: Record<string, any>;
 
   /** GitHub edit URL base */
   editUrl?: string;

standards/FRBR/docusaurus.config.old.ts

@@ -0,0 +1,46 @@
+import type { Config } from '@docusaurus/types';
+import preset, { getSiteConfig } from '../../packages/preset-ifla/dist/index.js';
+import navbarItems from './navbar';
+
+// Get site URLs based on environment
+const { url, baseUrl, env } = getSiteConfig('FRBR');
+
+const config: Config = {
+  ...preset(undefined as any, {
+    siteKey: 'FRBR',
+    title: 'IFLA FR Family of Models',
+    tagline: 'Conceptual Models for Bibliographic Information',
+    url,
+    baseUrl,
+    env,
+
+    // FRBR-specific vocabulary configuration
+    vocabularyDefaults: {
+      prefix: "ifla",
+      numberPrefix: "T",
+      profile: "vocabulary-profile.csv",
+      elementDefaults: {
+        uri: "https://www.iflastandards.info/elements",
+        classPrefix: "class",
+        propertyPrefix: "prop",
+        profile: "elements-profile.csv",
+        profileShapeId: "ElementShape",
+      }
+    },
+
+    // Custom navbar items
+    customNavbarItems: navbarItems,
+
+    // Navigation customization
+    navigation: {
+      hideCurrentSiteFromStandardsDropdown: true,
+      standardsDropdownPosition: 'right',
+      includeResourcesDropdown: false,
+    },
+
+    // GitHub configuration
+    editUrl: 'https://github.com/iflastandards/FRBR/tree/main/',
+  })
+};
+
+export default config;

standards/FRBR/docusaurus.config.ts

@@ -1,46 +1,2 @@
-import type { Config } from '@docusaurus/types';
-import preset, { getSiteConfig } from '../../packages/preset-ifla/dist/index.js';
-import navbarItems from './navbar';
-
-// Get site URLs based on environment
-const { url, baseUrl, env } = getSiteConfig('FRBR');
-
-const config: Config = {
-  ...preset(undefined as any, {
-    siteKey: 'FRBR',
-    title: 'IFLA FR Family of Models',
-    tagline: 'Conceptual Models for Bibliographic Information',
-    url,
-    baseUrl,
-    env,
-
-    // FRBR-specific vocabulary configuration
-    vocabularyDefaults: {
-      prefix: "ifla",
-      numberPrefix: "T",
-      profile: "vocabulary-profile.csv",
-      elementDefaults: {
-        uri: "https://www.iflastandards.info/elements",
-        classPrefix: "class",
-        propertyPrefix: "prop",
-        profile: "elements-profile.csv",
-        profileShapeId: "ElementShape",
-      }
-    },
-
-    // Custom navbar items
-    customNavbarItems: navbarItems,
-
-    // Navigation customization
-    navigation: {
-      hideCurrentSiteFromStandardsDropdown: true,
-      standardsDropdownPosition: 'right',
-      includeResourcesDropdown: false,
-    },
-
-    // GitHub configuration
-    editUrl: 'https://github.com/iflastandards/FRBR/tree/main/',
-  })
-};
-
-export default config;
+// Import the factory configuration to prevent build-time caching contamination
+export { default } from './docusaurus.config.factory.js';

standards/ISBDM/docusaurus.config.factory.ts

@@ -2,7 +2,6 @@ import type { Config } from '@docusaurus/types';
 import type { SidebarItemsGeneratorArgs, NormalizedSidebarItem } from '@docusaurus/plugin-content-docs/lib/sidebars/types';
 import preset from '../../packages/preset-ifla/dist/index.js';
 import { SiteConfigBuilder } from '../../packages/theme/dist/index.js';
-import { DocsEnv } from '../../packages/theme/dist/config/siteConfigCore.js';
 import navbarItems from './navbar';
 
 // Use the SiteConfigBuilder function to dynamically resolve configuration

standards/ISBDM/docusaurus.config.old.ts

@@ -0,0 +1,127 @@
+import type { Config } from '@docusaurus/types';
+import type { SidebarItemsGeneratorArgs, NormalizedSidebarItem } from '@docusaurus/plugin-content-docs/lib/sidebars/types';
+import preset, { getSiteConfig } from '../../packages/preset-ifla/dist/index.js';
+import navbarItems from './navbar';
+
+// Get site URLs based on environment
+const { url, baseUrl, env } = getSiteConfig('ISBDM');
+
+// Create a custom type that includes the undocumented `defaultSidebarItemsGenerator`
+type CustomSidebarItemsGeneratorArgs = SidebarItemsGeneratorArgs & {
+  defaultSidebarItemsGenerator: (args: SidebarItemsGeneratorArgs) => Promise<NormalizedSidebarItem[]> | NormalizedSidebarItem[];
+};
+
+// Custom sidebar generator for ISBDM
+const isbdmSidebarGenerator = async (generatorArgs: SidebarItemsGeneratorArgs) => {
+  const { defaultSidebarItemsGenerator, ...args } = generatorArgs as CustomSidebarItemsGeneratorArgs;
+  const sidebarItems: NormalizedSidebarItem[] = await defaultSidebarItemsGenerator(args);
+
+  function filterIndexMdx(items: NormalizedSidebarItem[]): NormalizedSidebarItem[] {
+    return items
+      .filter((item: NormalizedSidebarItem) => {
+        if (item.type === 'doc') {
+          const docId = item.id || (item as any).docId || '';
+          if (docId === 'index' ||
+              docId.endsWith('/index') ||
+              docId.split('/').pop() === 'index') {
+            return false;
+          }
+        }
+        return true;
+      })
+      .map((item: NormalizedSidebarItem) => {
+        if (item.type === 'category' && item.items) {
+          return {
+            ...item,
+            items: filterIndexMdx(item.items as NormalizedSidebarItem[]),
+          };
+        }
+        return item;
+      });
+  }
+
+  return filterIndexMdx(sidebarItems);
+};
+
+const config: Config = {
+  ...preset(undefined as any, {
+    siteKey: 'ISBDM',
+    title: 'ISBD for Manifestation',
+    tagline: 'International Standard Bibliographic Description for Manifestation',
+    url,
+    baseUrl,
+    env,
+
+    // ISBDM-specific vocabulary configuration
+    vocabularyDefaults: {
+      prefix: "isbdm",
+      numberPrefix: "T",
+      profile: "isbdm-values-profile-revised.csv",
+      elementDefaults: {
+        uri: "https://www.iflastandards.info/ISBDM/elements",
+        classPrefix: "class",
+        propertyPrefix: "prop",
+        profile: "isbdm-elements-profile.csv",
+        profileShapeId: "ElementShape",
+      }
+    },
+
+    // Custom navbar items
+    customNavbarItems: navbarItems,
+
+    // Navigation customization
+    navigation: {
+      hideCurrentSiteFromStandardsDropdown: true,
+      standardsDropdownPosition: 'right',
+      includeResourcesDropdown: false,
+      includeDocumentationItem: false, // ISBDM has custom navigation structure
+    },
+
+    // Footer customization
+    footer: {
+      additionalResourceLinks: [],
+    },
+
+    // Custom redirects for ISBDM
+    redirects: {
+      redirects: [],
+      createRedirects: (existingPath: string) => {
+        // Only process element paths - be very specific to avoid interfering with other routes
+        // This regex specifically matches element paths with numeric IDs only
+        const elementMatch = existingPath.match(/^\/docs\/(attributes|statements|notes|relationships)\/(\d+)$/);
+        if (elementMatch) {
+          const elementId = elementMatch[2];
+          // Only create redirect if it's a valid numeric element ID
+          if (/^\d+$/.test(elementId)) {
+            return [`/docs/elements/${elementId}`];
+          }
+        }
+        // Don't redirect anything else - this prevents interference with other routes
+        return undefined;
+      },
+    },
+
+    // Use custom sidebar generator
+    customSidebarGenerator: true,
+
+    // GitHub configuration
+    editUrl: 'https://github.com/iflastandards/ISBDM/tree/main/',
+
+    // Override settings for ISBDM
+    overrides: {
+      onBrokenLinks: 'ignore', // Override: ignore generated element links
+      onBrokenAnchors: 'ignore', // Override: ignore generated anchor links
+      onBrokenMarkdownLinks: 'ignore', // Override: ignore generated markdown links
+    }
+  })
+};
+
+// Apply custom sidebar generator to the config
+if (config.presets && config.presets[0] && Array.isArray(config.presets[0]) && config.presets[0][1]) {
+  const presetOptions = config.presets[0][1] as any;
+  if (presetOptions.docs) {
+    presetOptions.docs.sidebarItemsGenerator = isbdmSidebarGenerator;
+  }
+}
+
+export default config;