jonphipps
diff --git a/‎developer_notes/current-scaffolding-plan.md‎
Lines changed: 160 additions & 95 deletions b/‎developer_notes/current-scaffolding-plan.md‎
Lines changed: 160 additions & 95 deletions
@@ -1,97 +1,162 @@
-# Current Site Scaffolding Plan
-**IMPORTANT: Read and update this before each phase**
+# Current Site Scaffolding System
+**Status: COMPLETED AND OPERATIONAL**
 
 ## Overview
-The scaffolding system consists of two main scripts:
-1. **scaffold-site.ts** - Uses `scripts/scaffold-template` directory to establish folders and static files for a new site
-2. **generate-individual-config.ts** - Generates the docusaurus.config.ts file by:
-   - Loading a `site-config.json` file from the site directory (built from future form/wizard)
-   - Using this config data to generate a self-contained docusaurus.config.ts
-   - For re-scaffolding existing sites: store site-config.json in existing directory
-   - For new sites: store site-config.json in newly created directory
-
-## Phase 1: Move siteConfig.ts to Theme & Update Template Generator
-**Move configuration logic and fix template generation:**
-
-1. **Move siteConfig.ts** from `libs/shared-config/src/lib/` to `packages/theme/src/config/`
-2. **Update site-template.ts** to generate self-contained docusaurus.config.ts:
-   - Inline the SITE_CONFIG data structure directly in generated config
-   - Inline getSiteConfig function directly in generated config
-   - **Error handling**: If no DOCS_ENV, throw clear error (don't substitute)
-   - Add siteConfigMap to customFields for sister site URLs
-3. **Add new site support** to SITE_CONFIG for testing new site scaffolding
-
-## Phase 2: Fix UNIMARC URL/BaseURL Resolution
-**Update UNIMARC to use proper environment resolution:**
-
-1. UNIMARC is already good except for hardcoded url/baseUrl
-2. Replace hardcoded values with environment-based resolution using DOCS_ENV
-3. **Test using existing scripts**: `build:unimarc`, `start:unimarc`, etc.
-4. Verify isolation and no contamination
-
-## Phase 3: Re-scaffold Existing Sites (Moved ahead of scaffold-site)
-**Apply clean configs to eliminate contamination:**
-
-### Procedure for Each Site:
-1. **Make a backup** of the site's current docusaurus.config.ts (e.g., `mv docusaurus.config.ts docusaurus.config.ts.backup-YYYYMMDD`)
-2. **Read that config** to extract values and build a site-config.json
-3. **Load that JSON file** in the generate-individual-config.ts script and generate a new docusaurus.config.ts
-4. **Compare the generated config** to a known-good config (e.g., correct unimarc config) for structure/patterns
-5. **Refine if needed** and then build the site using the new config
-6. **Serve the site** and run visual regression tests:
-   - Use `pnpm test:visual-regression` with the visual-regression.spec.ts test
-   - Compare against baseline snapshots in ./tests
-7. **Manual review** - Have user look at it and offer suggestions
-
-**Note**: Can rename existing docusaurus.config.ts instead of copying for backup
-
-### Sites to Re-scaffold:
-1. ✅ **LRM** (Library Reference Model) - **COMPLETED**
-   - Generated site-config.json from existing config
-   - Used updated generate-individual-config.ts script
-   - Fixed import path: `@ifla/theme/config/siteConfig` (not `@ifla/theme`)
-   - Fixed navbar docId: `intro/intro` (due to folder structure)
-   - **Build successful**: `DOCS_ENV=local pnpm build:lrm --skip-nx-cache`
-   - **Server working**: `DOCS_ENV=local pnpm serve:lrm` → http://localhost:3002/LRM/
-   - **Known issues**: Some broken links to placeholder content (expected)
-2. **muldicat** → **isbd** → others using updated template
-3. **Test each site individually** using their own build/serve scripts (e.g., `build:muldicat`)
-
-### Key Fixes for LRM Re-scaffolding:
-- **Import path must be specific**: Use `@ifla/theme/config/siteConfig` to avoid React component loading during config phase
-- **Document structure matters**: LRM has `intro/intro.mdx` not `intro.mdx`, so navbar needs `docId: 'intro/intro'`
-- **Site-config.json template works**: Template in `scripts/scaffold-template/site-config.json` successfully generates configs
-
-## Phase 4: Enhanced Scaffold-Site Script  
-**Complete the scaffolding system:**
-
-1. **Hybrid approach**: Copy from scaffold-template directory + generate clean config
-2. **Support both**: re-scaffolding existing sites AND creating entirely new sites
-3. **Leverage existing infrastructure**: Use testsite pattern and existing package.json scripts
-
-## Key Points:
-- ✅ Move siteConfig to theme (eliminate shared-config dependency)
-- ✅ Generate completely self-contained configs (no imports)
-- ✅ Backup existing configs before re-scaffolding
-- ✅ Test each site with its own scripts
-- ✅ Handle new sites in SITE_CONFIG for testing
-- ✅ Error if DOCS_ENV missing (don't substitute)
-
-## Progress Tracking:
-- [x] Phase 1: Move siteConfig & Update Template
-  - ✅ Moved siteConfig.ts from shared-config to theme
-  - ✅ Added test site support (testsite, newtest) 
-  - ✅ Updated individualConfigTemplate to be self-contained (inline SITE_CONFIG)
-  - ✅ Added siteConfigMap to customFields
-  - ✅ Updated footer Portal link to use siteConfigMap
-  - ✅ Built theme successfully
-- [x] Phase 2: Fix UNIMARC
-  - ✅ Generated new self-contained config using updated template
-  - ✅ Replaced hardcoded URLs with environment-based resolution
-  - ✅ Tested build with multiple environments (local, preview)
-  - ✅ Verified isolation and no contamination
-  - ✅ Fixed copyright image path to use relative URL
-- [ ] Phase 3: Re-scaffold Sites
-- [ ] Phase 4: Enhanced Scaffold Script
-
-Last Updated: 2025-01-26
+The scaffolding system is a complete site generation framework that creates new IFLA standards sites with:
+- **Comprehensive template structure** matching the current ISBD pattern
+- **Dynamic configuration generation** from template files
+- **Rich content structure** with tabbed overview pages
+- **Consistent UI components** and styling
+
+### Core Components:
+1. **scaffold-site.ts** - Main scaffolding script using the complete template system
+2. **scaffold-template/** - Complete site template with all structure and components
+3. **site-template.ts** - Template generation logic with placeholder replacement
+4. **Individual site configs** - Self-contained configurations for each site
+
+## Current Scaffold Template Structure
+
+### **Template Files (Generated):**
+- **`docusaurus.config.ts.template`** - Complete Docusaurus configuration with placeholders
+- **`project.json.template`** - Nx project configuration for workspace integration
+
+### **Content Structure:**
+```
+scripts/scaffold-template/
+├── docs/
+│   ├── index.mdx                    # Tabbed overview (Element Sets, Vocabularies, Documentation)
+│   ├── about.mdx                    # Standard background and history
+│   ├── assessment.mdx               # Implementation guidelines
+│   ├── examples.mdx                 # Practical usage examples
+│   ├── glossary.mdx                 # Key terms and definitions
+│   ├── introduction.mdx             # Getting started guide
+│   ├── elements/index.mdx           # Elements overview with DocCardList
+│   └── terms/index.mdx              # Vocabularies overview with DocCardList
+├── src/
+│   ├── pages/
+│   │   ├── index.mdx                # Homepage with IFLA branding
+│   │   ├── manage.mdx               # Management dashboard
+│   │   ├── rdf.tsx                  # RDF downloads page
+│   │   ├── sitemap.module.scss      # Sitemap styling
+│   │   └── sitemap.tsx              # Sitemap component
+│   ├── components/
+│   │   ├── CompactButton.tsx        # Reusable button component
+│   │   └── CompactButton.module.css # Button styling
+│   └── css/custom.scss              # Site-specific styles
+├── blog/
+│   └── authors.yml                  # Blog authors template
+├── rdf/                             # RDF output directories (with .gitkeep files)
+│   ├── jsonld/ ├── nt/ ├── ttl/ └── xml/
+├── static/img/                      # Static assets (with .gitkeep)
+├── tsconfig.json                    # TypeScript configuration
+├── sidebars.ts                      # Navigation structure
+└── site-config.json                # Configuration placeholder
+```
+
+### **Key Features:**
+
+#### **Tabbed Overview Page:**
+- **Element Sets tab**: Shows constrained and unconstrained elements
+- **Value Vocabularies tab**: Displays primary, supporting, and extension vocabularies  
+- **Documentation tab**: Links to all documentation sections
+- **CompactButton component**: Consistent navigation styling
+
+#### **Template Placeholders:**
+- `{{TITLE}}` - Site title
+- `{{TAGLINE}}` - Site tagline/description
+- `{{SITE_KEY}}` - Site identifier (e.g., 'isbd', 'lrm')
+- `{{SITE_KEY_LOWER}}` - Lowercase site key
+- `{{PORT}}` - Development server port
+- `{{VOCABULARY_PREFIX}}` - Vocabulary URI prefix
+- `{{ELEMENT_URI}}` - Element namespace URI
+- `{{PROJECT_NAME}}` - GitHub project name
+- `{{NAVBAR_TITLE}}` - Navigation bar title
+- `{{SITE_CODE}}` - Short site code
+- `{{LAST_UPDATED}}` - Last modification date
+
+## Scaffolding Workflow
+
+### **Creating a New Site:**
+```bash
+pnpm tsx scripts/scaffold-site.ts \
+  --siteKey=newsite \
+  --title="New Standard" \
+  --tagline="A new IFLA standard"
+```
+
+### **What Happens:**
+1. **Validates site key** (alphanumeric, starts with letter, max 20 chars)
+2. **Creates directory structure** from scaffold-template
+3. **Generates configurations** from .template files with placeholder replacement
+4. **Updates package.json** with site-specific scripts
+5. **Creates blog content** from site configuration
+6. **Sets up Nx integration** with proper dependencies
+
+### **Template Integration:**
+- **Uses ISBD pattern**: Matches current ISBD site structure and styling
+- **Component consistency**: Shared CompactButton and navigation patterns
+- **Theme integration**: Leverages @ifla/theme components and utilities
+- **TypeScript compliant**: Full type safety and IntelliSense support
+
+## Component Documentation
+
+### **CompactButton Component:**
+```typescript
+interface CompactButtonProps {
+  href: string;
+  children: React.ReactNode;
+}
+```
+- **Usage**: Navigation buttons in tabbed overview and documentation pages
+- **Styling**: CSS module with consistent IFLA theme styling
+- **Integration**: Uses @ifla/theme InLink component for site-aware navigation
+
+### **Template Configuration:**
+- **TypeScript compliant**: Full composite project setup with references
+- **Nx integration**: Proper workspace dependencies and caching
+- **SCSS support**: Updated from CSS to SCSS for consistency
+- **Port management**: Automatic port assignment and conflict resolution
+
+## Maintenance Guide
+
+### **Updating the Scaffold Template:**
+When making changes that should apply to all future sites:
+
+1. **Update template files** in `scripts/scaffold-template/`
+2. **Test template generation** with scaffold-site script
+3. **Verify TypeScript compilation** and lint checks
+4. **Update documentation** if structure changes
+5. **Consider impact** on existing sites (may need migration)
+
+### **Adding New Template Features:**
+1. **Add to scaffold-template/** with appropriate placeholders
+2. **Update site-template.ts** if new placeholders needed
+3. **Test with actual site generation**
+4. **Document new features** in this file and README
+
+### **Troubleshooting:**
+- **Build failures**: Check TypeScript configuration and theme references
+- **Missing components**: Ensure CompactButton and other dependencies are copied
+- **Port conflicts**: Use robust startup commands or port manager
+- **Broken links**: Verify placeholder replacement and site structure
+
+## Current Status
+- ✅ **Scaffold template**: Complete with ISBD-matching structure
+- ✅ **Component system**: CompactButton and tabbed overview implemented
+- ✅ **Configuration generation**: Self-contained configs with proper isolation
+- ✅ **Nx integration**: Full workspace support with dependencies
+- ✅ **TypeScript compliance**: Composite projects with proper references
+- ✅ **Testing integration**: Pre-commit and build validation
+- ✅ **Documentation**: Rich content structure with professional presentation
+
+## Active Sites Using Template:
+- **Portal**: Management and landing site
+- **ISBD**: International Standard Bibliographic Description
+- **ISBDM**: ISBD Manifesto
+- **LRM**: Library Reference Model  
+- **FRBR**: Functional Requirements for Bibliographic Records
+- **MulDiCat**: Multilingual Dictionary of Cataloguing
+- **UniMARC**: Universal MARC format
+- **NewTest**: Testing site for new features
+
+Last Updated: 2025-01-30