feat: offload legacy enterprise docs to archive site

[llewellyn-sl]

Summary

• add DOCS_SITE_MODE-driven main vs enterprise-archive behavior for Platform Enterprise docs
• move Enterprise 23.1-23.4 into an archive-only build and add main-site redirects plus a legacy/supported version split in the UI
• make archive mode previewable locally without fetching unrelated OSS doc repos

Validation

• DOCS_SITE_MODE=enterprise-archive ./node_modules/.bin/docusaurus build --out-dir build-archive
• DOCS_SITE_MODE=main EXCLUDE_MULTIQC=true EXCLUDE_WAVE=true ./node_modules/.bin/docusaurus build --out-dir build-main
• DOCS_SITE_MODE=enterprise-archive npm run dev

Notes

• 23.1/23.2 legacy sidebars needed cleanup because they referenced docs that no longer exist on master
• archive builds still surface pre-existing broken-link/broken-anchor warnings inside legacy docs content
• follow-up deployment work is still needed after merge: create the frozen archive branch/site and configure docs-archive.seqera.io in Netlify

[netlify]

✅ Deploy Preview for seqera-docs ready!

Name	Link
🔨 Latest commit	23ac025
🔍 Latest deploy log	https://app.netlify.com/projects/seqera-docs/deploys/69ae878b39fd18000846aea9
😎 Deploy Preview	https://deploy-preview-1187--seqera-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[llewellyn-sl]

@claude review

[claude]

Claude finished @llewellyn-sl's task —— View job

---

PR Review: Enterprise Docs Archive Feature

This is a well-architected implementation for offloading legacy enterprise documentation to an archive site. Here's my comprehensive review:

Architecture & Design ✅

Excellent approach: The DOCS_SITE_MODE environment variable strategy cleanly separates main site (docs.seqera.io) from archive site (docs-archive.seqera.io) functionality.

Key strengths:

• Clean separation of concerns with mode-driven configuration
• Proper version segregation (24.1+ on main, 23.1-23.4 on archive)
• Smart build optimization (skips OSS docs fetch for archive mode)

Code Quality Review

docusaurus.config.js - Excellent

• Well-structured version management with enterpriseVersionsBySiteMode
• Proper conditional plugin loading to reduce archive site bloat
• Good use of custom fields for cross-component communication
• Smart announcement bar for archive site user guidance

React Components - Very Good

• VersionSwitcher/index.tsx: Clean implementation with proper TypeScript interfaces, good UX with "Legacy versions" external link
• Navbar/Content/index.tsx: Proper conditional rendering for archive vs main navbar
• SearchBar.tsx: Appropriate search disabling for archive site

Build System - Good

• prepare-site.mjs: Simple and effective OSS docs fetch bypass
• New npm scripts (dev:archive, build:archive) provide good DX

Potential Issues & Suggestions

Minor Issues:

1. docusaurus.config.js:364 - Inconsistent spacing in concatenateModules: false (extra space)
2. SearchBar.tsx - Consider adding JSDoc comment explaining why search is disabled for archive
3. Version handling - The hardcoded version arrays work but consider if they could be derived from platform-enterprise_versions.json

Deployment Concerns:

• Netlify redirects look correct for legacy versions
• Archive site URL (docs-archive.seqera.io) is properly configured
• Good separation of tracking (different GTM containers would be ideal)

Security & Performance ✅

• No security issues identified
• Good performance optimizations (plugin exclusions for archive)
• Proper external link handling with rel="noopener noreferrer"
• Build memory optimizations maintained

Testing & Validation

The validation commands in the PR description are comprehensive:

• ✅ Archive build: DOCS_SITE_MODE=enterprise-archive ./node_modules/.bin/docusaurus build
• ✅ Main build: DOCS_SITE_MODE=main EXCLUDE_MULTIQC=true EXCLUDE_WAVE=true ./node_modules/.bin/docusaurus build
• ✅ Archive dev: DOCS_SITE_MODE=enterprise-archive npm run dev

Final Assessment

This is a solid, production-ready implementation. The code is well-structured, follows good practices, and addresses the requirements effectively. The minor formatting issue is cosmetic.

Recommendation: ✅ APPROVE

The follow-up deployment work mentioned (creating frozen archive branch and Netlify configuration) is correctly identified as post-merge tasks.

---

[gavinelder]

@claude I am curious about this approach.

As we have two netlify sites, can we have two netlify configs and treat this as a mono-repo much like https://github.com/facebook/docusaurus/tree/main/website does ?

This means we only manage redirects inside of the core app for these sites rather than build commands ?

[claude]

Claude finished @gavinelder's task —— View job

---

Great question about the architectural approach! Let me analyze both the current implementation and the mono-repo alternative you're suggesting.

Todo List

• Analyze current single-config approach with DOCS_SITE_MODE
• Research Docusaurus mono-repo example structure
• Compare pros/cons of both architectural approaches
• Provide recommendation with reasoning

Current Implementation Analysis

The current approach uses a single Docusaurus config with DOCS_SITE_MODE environment variable to drive two different site behaviors:

Architecture:

• Single docusaurus.config.js with conditional logic
• DOCS_SITE_MODE = "main" (docs.seqera.io) or "enterprise-archive" (docs-archive.seqera.io)
• Version splitting: main gets 24.1+, archive gets 23.1-23.4
• Single netlify.toml with redirects pointing legacy URLs to archive site
• Conditional plugin loading and content exclusion

Alternative: Mono-repo with Separate Configs

The Docusaurus mono-repo approach would involve:

Structure:

├── docs-main/
│   ├── docusaurus.config.js
│   ├── netlify.toml
│   └── package.json
├── docs-archive/
│   ├── docusaurus.config.js
│   ├── netlify.toml
│   └── package.json
└── shared/
    └── [shared content & configs]

Comparison Analysis

Aspect	Current (Single Config)	Mono-repo (Dual Config)
Deployment Simplicity	✅ One config to maintain	❌ Two separate configs
Build Logic	✅ Centralized conditionals	✅ Simpler per-site logic
Content Management	✅ Single source of truth	❌ Potential duplication
Version Management	✅ Centralized version arrays	❌ Need sync between configs
Netlify Management	✅ Single site + redirects	❌ Two separate Netlify sites
CI/CD Complexity	✅ One build pipeline	❌ Two build pipelines
Environment Drift	✅ Shared dependencies	⚠️ Risk of config drift
Redirect Management	✅ Netlify handles cross-site redirects	❌ More complex routing

Specific Trade-offs

Current Approach Strengths:

• Single source of truth: Version definitions, shared components, and configurations are centralized
• Simpler deployment: One codebase, one build process, one deployment pipeline
• Easier maintenance: Updates to shared logic happen once
• Netlify redirect efficiency: Built-in redirect handling works seamlessly
• Cost efficiency: One Netlify site vs two

Mono-repo Approach Benefits:

• Cleaner separation: Each site has its own focused config
• Independent scaling: Sites can evolve independently
• Simpler debugging: Less conditional logic in configs
• Future flexibility: Easier to diverge architectures if needed

Recommendation

I recommend sticking with the current single-config approach for these reasons:

1. Your use case is ideal for single-config: The archive site is essentially a frozen subset of the main site, not a fundamentally different application
2. Maintenance burden: Managing version arrays, shared components, and dependencies across two configs would create ongoing sync challenges
3. Netlify economics: Two sites = 2x costs, 2x complexity
4. Content overlap: Both sites share substantial content (themes, components, assets) that would need to be duplicated or symlinked

When to Consider Mono-repo

The mono-repo approach would make sense if:

• Archive and main sites had fundamentally different architectures
• Sites needed independent release cycles
• Different teams owned each site
• Sites used different tech stacks or major version differences

Suggested Improvements to Current Approach

If you want to enhance the current architecture:

1. Extract version management: Move enterpriseVersionsBySiteMode to a separate JSON file
2. Add validation: Ensure version arrays don't overlap
3. Enhance testing: Add integration tests for both site modes
4. Document the pattern: Make the DOCS_SITE_MODE pattern reusable for future site variants

The current implementation is well-architected for this specific use case. The conditional complexity is manageable and centralized, making it easier to maintain than duplicate configurations.

---

**