Add GitLab CI configuration for MkDocs Material with preview deployments

- Production deployment to https://satware.ai (main branch)
- Preview deployments to https://satware.ai/feature/xyz (feature branches)
- Replicates GitHub Actions build process exactly
- Supports custom SCSS compilation
- Automated cleanup of old preview environments

.gitlab-ci.yml

@@ -0,0 +1,262 @@
+# GitLab CI Configuration for satware.ai MkDocs Material Site
+# Migrated from GitHub Actions with preview deployment support
+
+stages:
+  - build
+  - deploy
+  - cleanup
+
+variables:
+  # Python and dependency versions (matching GitHub Actions exactly)
+  PYTHON_VERSION: "3.13"
+  MKDOCS_MATERIAL_VERSION: "9.6.14"
+  
+  # Site configuration
+  PRODUCTION_URL: "https://satware.ai"
+  PREVIEW_BASE_URL: "https://satware.ai"
+
+# 🔧 Build Job Template (shared between production and preview)
+.build_template: &build_template
+  image: python:${PYTHON_VERSION}-slim
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - .cache/
+      - venv/
+  before_script:
+    # Install system dependencies for MkDocs Material
+    - apt-get update && apt-get install -y 
+        build-essential 
+        git 
+        libcairo2-dev 
+        libfreetype6-dev 
+        libffi-dev 
+        libjpeg-dev 
+        libpng-dev 
+        libz-dev
+    
+    # Setup Python virtual environment
+    - python -m venv venv
+    - source venv/bin/activate
+    - pip install --upgrade pip
+    
+    # Install exact same dependencies as GitHub Actions
+    - pip install 
+        cairosvg 
+        libsass 
+        mkdocs-exclude 
+        mkdocs-git-revision-date-localized-plugin 
+        mkdocs-glightbox 
+        mkdocs-include-markdown-plugin 
+        mkdocs-literate-nav 
+        mkdocs-macros-plugin 
+        mkdocs-material==${MKDOCS_MATERIAL_VERSION}
+        "mkdocs-material[imaging]" 
+        mkdocs-minify-plugin 
+        mkdocs-redirects 
+        mkdocs-rss-plugin 
+        mkdocs-snippets 
+        mkdocs-video 
+        watchdog
+
+  script:
+    - source venv/bin/activate
+    
+    # Build custom CSS from SCSS (exactly like GitHub Actions)
+    - mkdir -p docs/assets/css
+    - pysassc overrides/assets/css/custom.scss docs/assets/css/custom.css
+    
+    # Configure site_url based on deployment type
+    - |
+      if [ "$CI_COMMIT_REF_NAME" = "main" ] || [ "$CI_COMMIT_REF_NAME" = "main-mkdocs" ]; then
+        echo "📍 Production deployment to ${PRODUCTION_URL}"
+        # Keep original site_url for production
+        echo "Site URL: $(grep '^site_url:' mkdocs.yml)"
+      else
+        echo "🔍 Preview deployment for branch: ${CI_COMMIT_REF_NAME}"
+        # Extract clean branch name for URL path
+        BRANCH_PATH=$(echo "${CI_COMMIT_REF_NAME}" | sed 's|feature/||g' | sed 's|fix/||g' | sed 's|blog/||g' | sed 's|[^a-zA-Z0-9-]|-|g' | tr '[:upper:]' '[:lower:]')
+        PREVIEW_URL="${PREVIEW_BASE_URL}/${BRANCH_PATH}/"
+        
+        echo "📝 Updating site_url to: ${PREVIEW_URL}"
+        # Update site_url for preview deployment
+        if grep -q "^site_url:" mkdocs.yml; then
+          sed -i "s|^site_url:.*|site_url: ${PREVIEW_URL}|" mkdocs.yml
+        else
+          echo "site_url: ${PREVIEW_URL}" >> mkdocs.yml
+        fi
+        
+        # Also update use_directory_urls for better preview navigation
+        if grep -q "^use_directory_urls:" mkdocs.yml; then
+          sed -i "s|^use_directory_urls:.*|use_directory_urls: true|" mkdocs.yml
+        fi
+        
+        echo "✅ Updated mkdocs.yml for preview:"
+        grep -E "^(site_url|use_directory_urls):" mkdocs.yml
+      fi
+    
+    # Build the static site
+    - echo "🏗️ Building MkDocs site..."
+    - mkdocs build --verbose
+    
+    # Verify build output
+    - echo "📊 Build output summary:"
+    - ls -la site/
+    - echo "📄 Sample files:"
+    - find site/ -name "*.html" -type f | head -5
+
+  artifacts:
+    paths:
+      - site/
+    expire_in: 1 hour
+    reports:
+      # Generate deployment report
+      dotenv: deploy.env
+
+# 🌐 Production Deployment (main branch -> https://satware.ai)
+pages:
+  <<: *build_template
+  stage: deploy
+  rules:
+    - if: $CI_COMMIT_REF_NAME == "main-mkdocs"
+    - if: $CI_COMMIT_REF_NAME == "main"
+  script:
+    # Run the build template script
+    - !reference [.build_template, script]
+    
+    # Prepare for GitLab Pages (requires 'public' directory)
+    - echo "📦 Preparing production deployment..."
+    - mv site public
+    
+    # Generate deployment info
+    - echo "DEPLOYMENT_URL=${PRODUCTION_URL}" > deploy.env
+    - echo "DEPLOYMENT_TYPE=production" >> deploy.env
+    - echo "BRANCH=${CI_COMMIT_REF_NAME}" >> deploy.env
+    - echo "COMMIT=${CI_COMMIT_SHA}" >> deploy.env
+    
+    # Deployment summary
+    - echo "🚀 Production deployment ready:"
+    - echo "   📍 URL: ${PRODUCTION_URL}"
+    - echo "   🌿 Branch: ${CI_COMMIT_REF_NAME}"
+    - echo "   📦 Files: $(find public -type f | wc -l)"
+    - echo "   💾 Size: $(du -sh public | cut -f1)"
+
+  artifacts:
+    paths:
+      - public
+    reports:
+      dotenv: deploy.env
+  environment:
+    name: production
+    url: ${PRODUCTION_URL}
+
+# 🔍 Preview Deployment (feature branches -> https://satware.ai/feature/xyz)
+preview:
+  <<: *build_template
+  stage: deploy
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_REF_NAME =~ /^(feature|fix|blog|test|preview)\/.*/
+    - if: $CI_COMMIT_REF_NAME =~ /^(develop|staging)$/
+  script:
+    # Run the build template script
+    - !reference [.build_template, script]
+    
+    # Extract clean branch name for environment
+    - BRANCH_PATH=$(echo "${CI_COMMIT_REF_NAME}" | sed 's|feature/||g' | sed 's|fix/||g' | sed 's|blog/||g' | sed 's|[^a-zA-Z0-9-]|-|g' | tr '[:upper:]' '[:lower:]')
+    - PREVIEW_URL="${PREVIEW_BASE_URL}/${BRANCH_PATH}/"
+    
+    # For preview, we'll create a deployable artifact that can be manually deployed
+    # (This will require custom deployment setup to your satware.ai server)
+    - mkdir -p preview-deploy/${BRANCH_PATH}
+    - cp -r site/* preview-deploy/${BRANCH_PATH}/
+    
+    # Generate deployment info
+    - echo "DEPLOYMENT_URL=${PREVIEW_URL}" > deploy.env
+    - echo "DEPLOYMENT_TYPE=preview" >> deploy.env
+    - echo "BRANCH=${CI_COMMIT_REF_NAME}" >> deploy.env
+    - echo "BRANCH_PATH=${BRANCH_PATH}" >> deploy.env
+    - echo "COMMIT=${CI_COMMIT_SHA}" >> deploy.env
+    
+    # Create deployment instructions
+    - |
+      cat > DEPLOY_INSTRUCTIONS.md << EOF
+      # 🔍 Preview Deployment Instructions
+      
+      **Branch:** \`${CI_COMMIT_REF_NAME}\`  
+      **Preview URL:** ${PREVIEW_URL}  
+      **Commit:** \`${CI_COMMIT_SHA}\`  
+      
+      ## Manual Deployment Steps:
+      
+      1. Download the \`preview-deploy\` artifact from this pipeline
+      2. Extract to your satware.ai server under path: \`/${BRANCH_PATH}/\`
+      3. Ensure web server serves files from this location
+      4. Access preview at: ${PREVIEW_URL}
+      
+      ## Automated Deployment (Future):
+      Configure rsync/ssh to automatically deploy to your server:
+      \`\`\`bash
+      rsync -avz --delete preview-deploy/${BRANCH_PATH}/ user@satware.ai:/var/www/satware.ai/${BRANCH_PATH}/
+      \`\`\`
+      EOF
+    
+    # Preview summary
+    - echo "🔍 Preview deployment ready:"
+    - echo "   📍 URL: ${PREVIEW_URL}"
+    - echo "   🌿 Branch: ${CI_COMMIT_REF_NAME}"
+    - echo "   📁 Path: /${BRANCH_PATH}/"
+    - echo "   📦 Files: $(find preview-deploy -type f | wc -l)"
+    - echo "   💾 Size: $(du -sh preview-deploy | cut -f1)"
+
+  artifacts:
+    paths:
+      - preview-deploy/
+      - DEPLOY_INSTRUCTIONS.md
+    expire_in: 7 days
+    reports:
+      dotenv: deploy.env
+  environment:
+    name: preview/${CI_COMMIT_REF_SLUG}
+    url: ${PREVIEW_BASE_URL}/${BRANCH_PATH}/
+    on_stop: cleanup_preview
+
+# 🧹 Cleanup Preview Environments (when branch is deleted)
+cleanup_preview:
+  stage: cleanup
+  image: alpine:latest
+  rules:
+    - if: $CI_COMMIT_REF_NAME =~ /^(feature|fix|blog|test|preview)\/.*/
+      when: manual
+      allow_failure: true
+  script:
+    - echo "🧹 Cleanup preview environment for ${CI_COMMIT_REF_NAME}"
+    - echo "Manual cleanup required - remove files from server path: /${BRANCH_PATH}/"
+    # Add your cleanup commands here, e.g.:
+    # - ssh user@satware.ai "rm -rf /var/www/satware.ai/${BRANCH_PATH}/"
+  environment:
+    name: preview/${CI_COMMIT_REF_SLUG}
+    action: stop
+
+# 📊 Build Information Job (runs on all branches for debugging)
+build_info:
+  stage: build
+  image: alpine:latest
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_REF_NAME =~ /.*/
+  script:
+    - echo "🔍 Build Information:"
+    - echo "   📁 Repository: ${CI_PROJECT_PATH}"
+    - echo "   🌿 Branch: ${CI_COMMIT_REF_NAME}"
+    - echo "   📝 Commit: ${CI_COMMIT_SHA:0:8}"
+    - echo "   👤 Author: ${GITLAB_USER_NAME}"
+    - echo "   📅 Pipeline: ${CI_PIPELINE_ID}"
+    - echo "   🔗 URL: ${CI_PIPELINE_URL}"
+    - |
+      if [ "$CI_COMMIT_REF_NAME" = "main" ] || [ "$CI_COMMIT_REF_NAME" = "main-mkdocs" ]; then
+        echo "   🚀 Deployment: Production (${PRODUCTION_URL})"
+      else
+        BRANCH_PATH=$(echo "${CI_COMMIT_REF_NAME}" | sed 's|feature/||g' | sed 's|fix/||g' | sed 's|blog/||g' | sed 's|[^a-zA-Z0-9-]|-|g' | tr '[:upper:]' '[:lower:]')
+        echo "   🔍 Deployment: Preview (${PREVIEW_BASE_URL}/${BRANCH_PATH}/)"
+      fi