MkDocs Versioning with Mike¶

This project uses mike to manage multiple versions of documentation, allowing users to access both current and historical documentation through a version selector dropdown.

Note: The .\scripts\mike-*.ps1 convenience wrappers referenced below (mike-build-ftp.ps1, mike-deploy.ps1, mike-alias.ps1, mike-list.ps1) are not present in the repo. Use the underlying mike commands directly — mike deploy, mike alias, mike list, mike serve — as documented in the raw-command sections of this guide. mike is configured (mkdocs.yml, docs-requirements.txt).

🎯 Benefits¶

✅ Three-tier organization - Hot (main nav), Warm (search only), Cold (version menu)
✅ Keep latest docs slim - Archive historical content to separate versions
✅ Version selector - Users can switch between versions via dropdown menu
✅ Professional approach - Industry-standard documentation versioning
✅ Preserve history - All historical documentation remains accessible
✅ Search-only archives - Archive files searchable but hidden from navigation sidebar

📦 Installation¶

Install mike along with MkDocs:

pip install -r docs-requirements.txt

Or install individually:

pip install mkdocs mkdocs-material mike

🚀 Quick Start¶

1. Build All Versions for FTP Deployment¶

For local testing or FTP deployment:

.\scripts\mike-build-ftp.ps1

This creates: - site/latest/ - Hot tier (current documentation, main nav) - site/v2025-archive/ - Warm tier (2025 archive, search only) - site/cold-storage/ - Cold tier (legacy documentation, version menu) - site/versions.json - Version selector data - site/index.html - Redirects to latest

2. Preview Locally¶

Preview the versioned documentation:

# Serve the built site
cd site
python -m http.server 8000

Then visit: http://localhost:8000

The version selector will appear in the header, allowing users to switch between: - Latest - Hot tier (current active documentation, main nav) - 2025 Archive (Warm) - Warm tier (2025 fixes, search only) - Cold Storage (Legacy) - Cold tier (legacy updates, version menu)

📋 Version Management¶

Deploy a New Version¶

For GitHub Pages (if using):

.\scripts\mike-deploy.ps1 -Version "1.0" -Alias "latest"

Set/Update an Alias¶

.\scripts\mike-alias.ps1 -Version "1.0" -Alias "latest"

List All Versions¶

.\scripts\mike-list.ps1

📂 Three-Tier Version Structure¶

🔥 Hot Tier - Latest Version (`mkdocs.yml`)¶

Location: docs/ (Main Nav)
Purpose: Active RF algorithms and recent bug fixes
Visibility: ✅ Visible in navigation sidebar
URL: https://pcbgenerator.com/docs/latest/

Navigation includes: - Home - Complete User Guide - Getting Started

Search-Only Archives: - Archive files (docs/archive/) are not shown in navigation to keep it clean - Archive files are fully searchable via the search box - Users can find historical content by searching, but it won't clutter the sidebar - Configured with search.indexing: 'full' to index all files including those not in nav

🌡️ Warm Tier - Archive Version (`mkdocs-archive.yml`)¶

Location: docs/archive/ (Search Only)
Purpose: Fixes from current year (2025); proof of validation
Visibility: ❌ Not in nav, ✅ Fully searchable
URL: https://pcbgenerator.com/docs/v2025-archive/

Content includes: - 2025 historical fixes (October fixes) - 2025 database updates - 2025 test documentation - Proof of validation for recent changes

Access: - Searchable via search box in latest version - Browseable in archive version navigation - Keeps main navigation clean while preserving current year history

🧊 Cold Tier - Cold Storage Version (`mkdocs-cold-storage.yml`)¶

Location: docs/cold-storage/ (Version Menu)
Purpose: Legacy database updates and refactoring logs
Visibility: ❌ Not in nav, ❌ Not searchable in latest, ✅ Accessible via version menu
URL: https://pcbgenerator.com/docs/cold-storage/

Content includes: - Legacy database updates (pre-2025 or early 2025) - Legacy refactoring summaries - Very old historical fixes - Completed major refactoring logs

Access: - Only accessible via version selector dropdown - Select "Cold Storage (Legacy)" from version menu - Not searchable in main/latest version - Preserves historical context without cluttering active docs

🔧 Configuration Files¶

`mkdocs.yml` (Hot Tier - Latest)¶

Standard configuration for current documentation. Archive folder is excluded from navigation but remains searchable.

Key features: - Archive files (docs/archive/) are not listed in nav section - Archive files are fully indexed for search via search.indexing: 'full' - Users can find historical content by searching, keeping navigation clean - Cold storage files are not indexed (only accessible via version menu)

`mkdocs-archive.yml` (Warm Tier - Archive)¶

Extended configuration that includes archive folder in navigation. Used for the v2025-archive version.

Key features: - Archive folder is visible in navigation for easy browsing - Full search indexing enabled for comprehensive search coverage - Contains 2025 fixes and updates (current year) - Accessible via search in latest version

`mkdocs-cold-storage.yml` (Cold Tier - Legacy)¶

Configuration for legacy documentation. Used for the cold-storage version.

Key features: - Cold storage folder is visible in navigation when viewing this version - Contains legacy database updates and refactoring logs - Only accessible via version selector dropdown - Not searchable in main/latest version

🔍 Search-Only Archives Feature¶

The latest version uses a "search-only" archive approach:

How it works: 1. Archive files remain in docs/archive/ folder 2. Archive is excluded from navigation (nav section) 3. Archive is fully indexed by search plugin (indexing: 'full') 4. Users can find archive content via search box, but it doesn't clutter the sidebar

Benefits: - ✅ Clean navigation - Only current, relevant docs visible - ✅ Full searchability - All content still discoverable - ✅ Better UX - Users see what they need, find what they want - ✅ Professional appearance - No overwhelming archive sections

Example: - User searches for "VCO selection algorithm" - Search results include both current docs AND archive/historical-fixes/VCO_SELECTION_PHASE_1_2_IMPLEMENTATION.md - Archive file appears in search results but not in navigation sidebar

🚀 Deployment¶

Automated (GitHub Actions)¶

The deployment workflow automatically: 1. Builds both versions (latest and v2025-archive) 2. Creates versioned directory structure 3. Deploys to Hostinger via FTP

Manual Deployment¶

Build versions:
```
.\scripts\mike-build-ftp.ps1
```
Upload to Hostinger:
Upload contents of site/ folder to public_html/docs/

Structure will be:

docs/
├── index.html (redirects to latest)
├── versions.json
├── latest/
└── v2025-archive/

Access:
Latest: https://pcbgenerator.com/docs/latest/
Archive: https://pcbgenerator.com/docs/v2025-archive/
Root: https://pcbgenerator.com/docs/ (redirects to latest)

🎨 Version Selector¶

The version selector appears automatically in the Material theme header when: - navigation.version feature is enabled (already configured) - mike plugin is configured (already configured) - versions.json exists (created during build)

Users can: - Click the version dropdown in the header - Select "Latest" or "2025 Archive" - Navigate seamlessly between versions

📝 Adding New Versions¶

To add a new version (e.g., v2026-archive):

Create new config (optional, if structure differs):
```
# mkdocs-v2026-archive.yml
```

Build the version:

mkdocs build --config-file mkdocs-v2026-archive.yml --site-dir site/v2026-archive --clean

Update versions.json: Add the new version to site/versions.json:

{
  "latest": {...},
  "v2025-archive": {...},
  "v2026-archive": {
    "version": "v2026-archive",
    "title": "2026 Archive",
    "aliases": ["archive-2026"]
  }
}

Update build script to include the new version

🔍 Troubleshooting¶

Version selector not appearing¶

Check that navigation.version is in theme.features
Verify mike plugin is configured in plugins
Ensure versions.json exists in site/

Build errors¶

Verify both mkdocs.yml and mkdocs-archive.yml are valid
Check that all referenced files exist
Ensure mike is installed: pip install mike

FTP deployment issues¶

Verify directory structure: site/latest/ and site/v2025-archive/ exist
Check that versions.json is uploaded
Ensure root index.html redirects correctly

📚 Additional Resources¶

🎯 Best Practices¶

Keep latest slim - Only include actively-used content in latest
Archive regularly - Move historical content to archive versions periodically
Version naming - Use semantic versioning or date-based versions (e.g., v2025-archive)
Test locally - Always preview versions before deploying
Document changes - Update this guide when adding new versions

Last Updated: January 2026 Maintained by: MagicON AI Development Team