Documentation Deployment Branch Strategy¶

2026-04-07

Overview¶

The ABS Platform documentation uses a branch-based deployment strategy to support different deployment targets while maintaining a single source of truth.

Branch Structure¶

`main` Branch (Default)¶

Purpose: Local development and primary documentation source
Layout: 2-column layout (left menu + right content, NO header tabs)
Configuration: mkdocs.yml (root level)
Features:
navigation.tabs: DISABLED
navigation.tabs.sticky: DISABLED
toc.follow: DISABLED
toc.integrate: DISABLED
Serving: python -m mkdocs serve

`HW-Design` Branch (Design & Content Testing)¶

Purpose: Personal workspace for style and content experimentation by HW
Owner: Huashan Wang
Layout: Same 2-column layout as main (can be modified for testing)
Use Cases:
Testing style changes (CSS, fonts, colors)
Content structure experiments
Documentation improvements
Local preview before merging to main
Workflow: Test locally → merge approved changes to main → developers deploy

`cloud-deploy` Branch (Cloud Deployment)¶

Purpose: Cloud hosting platforms (Azure Static Web Apps, GitHub Pages, etc.)
Owner: Development team
Layout: May include different navigation patterns optimized for cloud viewing
Configuration: Potentially different mkdocs.yml settings
Features: Cloud-specific optimizations as needed
Deployment: Automated via GitHub Actions

Developer Workflow¶

For HW (Design & Content Owner)¶

# Work on your personal design branch
git checkout HW-Design

# Make style/content changes
# - Edit CSS: docs/stylesheets/extra.css
# - Update content: docs/**/*.md
# - Modify layout: mkdocs.yml (for testing)

# Test locally
python -m mkdocs serve
# or
python scripts/krr.py

# Commit your changes
git add .
git commit -m "Design: [description of changes]"

# When ready to share with team, merge to main
git checkout main
git merge HW-Design
git push origin main

# Developers will then merge main -> cloud-deploy for deployment

For Local Development (Team)¶

# Always work on main branch
git checkout main

# Serve locally with 2-column layout
python -m mkdocs serve

# Or use KRR script
python scripts/krr.py

For Cloud Deployment Changes¶

# Create/checkout cloud deployment branch
git checkout -b cloud-deploy

# Make cloud-specific configuration changes
# Edit mkdocs.yml, extra.css, etc. as needed

# Build and test
mkdocs build

# Commit cloud-specific changes
git add .
git commit -m "Cloud deployment: [description]"

# Push to trigger deployment
git push origin cloud-deploy

Syncing Content from Main to Cloud¶

# Checkout cloud-deploy branch
git checkout cloud-deploy

# Merge content updates from main
git merge main

# Resolve any configuration conflicts
# (Keep cloud-specific settings in mkdocs.yml, extra.css)

# Push updated content
git push origin cloud-deploy

Configuration Differences¶

Main Branch Configuration¶

File: mkdocs.yml

features:
  # 2-column layout: left menu + right content (NO header tabs)
  # - navigation.tabs         # DISABLED
  # - navigation.tabs.sticky  # DISABLED
  - navigation.top
  - navigation.tracking
  - content.code.copy
  - content.code.annotate
  - search.highlight
  - search.share
  # - toc.follow             # DISABLED
  # - toc.integrate          # DISABLED

Cloud Branch Configuration (Example)¶

File: mkdocs.yml (on cloud-deploy branch)

features:
  # Cloud-optimized layout (if different)
  - navigation.tabs          # ENABLED for cloud if needed
  - navigation.tabs.sticky
  - navigation.top
  - navigation.tracking
  - content.code.copy
  - content.code.annotate
  - search.highlight
  - search.share
  - toc.follow              # ENABLED for cloud if needed
  - toc.integrate

GitHub Actions Integration¶

Automated Cloud Deployment¶

Create .github/workflows/deploy-docs.yml:

name: Deploy Documentation to Cloud

on:
  push:
    branches:
      - cloud-deploy

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install mkdocs-material==9.6.21
          pip install mkdocs-awesome-pages-plugin
          pip install mkdocs-git-revision-date-localized-plugin

      - name: Build documentation
        run: mkdocs build

      - name: Deploy to cloud
        # Add your cloud-specific deployment steps here
        # e.g., Azure Static Web Apps, GitHub Pages, etc.
        run: |
          echo "Deploy to your cloud provider"

Important Rules¶

DO NOT Modify Main Branch Layout¶

❌ NEVER re-enable navigation.tabs on main branch
❌ NEVER re-enable toc.integrate on main branch
✅ Main branch ALWAYS uses 2-column layout (approved design)

Cloud Branch Flexibility¶

✅ Cloud branch CAN have different layout if needed
✅ Cloud-specific CSS can be different
✅ Configuration changes isolated to cloud-deploy branch

Content Synchronization¶

✅ Content changes (markdown files) made on main
✅ Merge main → cloud-deploy regularly for content updates
✅ Resolve conflicts by keeping cloud-specific config

Rationale¶

Why branch-based? 1. Single Source: All documentation content lives in main branch 2. Deployment Flexibility: Different platforms may need different configurations 3. Isolation: Cloud-specific settings don't pollute local development 4. Easy Rollback: Can revert cloud config without affecting main 5. Clear Separation: Developers know which branch for which purpose

Common Scenarios¶

Scenario 1: HW Tests New Design/Content¶

# Work on HW-Design branch
git checkout HW-Design

# Make changes to CSS, content, or layout
# Test locally: python -m mkdocs serve

# Commit changes
git add .
git commit -m "Design: Updated navigation styling"

# When satisfied, merge to main
git checkout main
git merge HW-Design
git push origin main

# Notify developers to deploy
# Developers will: git checkout cloud-deploy && git merge main

Scenario 2: Update Documentation Content¶

# Work on main branch
git checkout main
# Edit markdown files
# Test locally: python -m mkdocs serve
git add docs/
git commit -m "Updated documentation content"
git push origin main

# Sync to cloud
git checkout cloud-deploy
git merge main
git push origin cloud-deploy  # Triggers deployment

Scenario 2: Change Cloud Layout/Theme¶

# Work on cloud-deploy branch
git checkout cloud-deploy
# Edit mkdocs.yml, extra.css for cloud-specific changes
git add mkdocs.yml docs/stylesheets/extra.css
git commit -m "Cloud: Updated navigation layout"
git push origin cloud-deploy  # Triggers deployment

# Main branch remains unchanged

Scenario 3: Fix Broken Links¶

# Fix on main branch (content issue)
git checkout main
# Fix relative paths in markdown files
git add docs/
git commit -m "Fixed broken relative links"
git push origin main

# Sync to cloud
git checkout cloud-deploy
git merge main
git push origin cloud-deploy

Deployment Checklist¶

Before Deploying to Cloud¶

[ ] All content changes merged from main
[ ] Cloud-specific configuration verified
[ ] Build completes without errors: mkdocs build
[ ] No broken links in build output
[ ] CSS/theme optimizations tested
[ ] Git repository clean (no uncommitted changes)

After Cloud Deployment¶

[ ] Verify site loads correctly
[ ] Check navigation works as expected
[ ] Verify search functionality
[ ] Test responsive design (mobile/tablet)
[ ] Confirm all links resolve correctly

Troubleshooting¶

Merge Conflicts Between Branches¶

# Common conflict files: mkdocs.yml, extra.css
git checkout cloud-deploy
git merge main

# If conflicts:
# 1. Keep cloud-specific settings in mkdocs.yml
# 2. Keep cloud-specific styles in extra.css
# 3. Accept all content changes from main

git add .
git commit -m "Merged content from main, kept cloud config"

Accidentally Changed Main Branch Layout¶

# Revert configuration changes
git checkout main
git checkout HEAD -- mkdocs.yml
git checkout HEAD -- docs/stylesheets/extra.css

# Or restore from last known good commit
git log --oneline mkdocs.yml  # Find good commit
git checkout <commit-hash> -- mkdocs.yml

References¶

MkDocs 2-Column Layout Design Standard - Approved layout configuration
MkDocs Relative Link Path Fix Pattern - Link path guidelines
Main branch layout is LOCKED and approved - do not modify without explicit approval

Last Updated: January 2025 Maintained By: System Architecture Team