pages.yml

name: Deploy Documentation to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'docs_site/**'
      - 'GUIDES/**'
      - 'README.md'
      - '.github/workflows/pages.yml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN || secrets.PAGES_TOKEN || github.token }}

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true
          working-directory: ./docs_site

      - name: Setup Pages
        uses: actions/configure-pages@v4
        continue-on-error: true

      - name: Build Jekyll site
        working-directory: ./docs_site
        env:
          JEKYLL_ENV: production
        run: |
          set -e
          REPO_NAME=$(echo ${{ github.repository }} | cut -d'/' -f2)
          CURRENT_YEAR=$(date +%Y)
          
          echo "🔨 Building Jekyll site with baseurl: /$REPO_NAME"
          
          # Build Jekyll site (generates index.html from index.md)
          # Suppress Sass deprecation warnings (they're harmless)
          bundle exec jekyll build --baseurl "/$REPO_NAME" 2>&1 | grep -v "DEPRECATION WARNING" || true
          
          # Verify build completed and index.html was generated
          if [ ! -f "_site/index.html" ]; then
            echo "❌ Build failed: index.html not generated in _site/"
            exit 1
          fi
          
          echo "✅ Jekyll build complete: _site/index.html generated"
          
          # Verify Mermaid.js is included in the layout
          if grep -q "mermaid" _site/architecture.html 2>/dev/null; then
            echo "✅ Mermaid.js script found in architecture.html"
          else
            echo "⚠️  Warning: Mermaid.js script not found in architecture.html"
          fi
          
          # Count Mermaid diagram blocks in source
          MERMAID_COUNT=$(grep -c '```mermaid' architecture.md 2>/dev/null || echo "0")
          echo "📊 Found $MERMAID_COUNT Mermaid diagram blocks in architecture.md"
          
          # Verify Mermaid code blocks are in HTML output
          MERMAID_HTML_COUNT=$(grep -c 'language-mermaid\|class="language-mermaid"' _site/architecture.html 2>/dev/null || echo "0")
          echo "📊 Found $MERMAID_HTML_COUNT Mermaid code blocks in architecture.html"
          
          if [ "$MERMAID_HTML_COUNT" = "0" ] && [ "$MERMAID_COUNT" != "0" ]; then
            echo "⚠️  Warning: Mermaid diagrams in markdown but not found in HTML output"
            echo "   This may indicate a markdown processing issue"
          fi
          
          # Verify key pages were built
          for page in index.html architecture.html getting_started.html; do
            if [ -f "_site/$page" ]; then
              echo "✅ Page built: $page"
            else
              echo "⚠️  Warning: Page not found: $page"
            fi
          done

      - name: Prepare artifact
        run: |
          set -e
          REPO_NAME=$(echo ${{ github.repository }} | cut -d'/' -f2)
          
          echo "📦 Preparing artifact for deployment..."
          
          # Create artifact structure at root: $REPO_NAME/
          mkdir -p $REPO_NAME
          
          # Copy all built files from docs_site/_site/ to root $REPO_NAME/
          cp -r docs_site/_site/* $REPO_NAME/ 2>/dev/null || true
          
          # Verify index.html was copied successfully
          if [ ! -f "$REPO_NAME/index.html" ]; then
            echo "❌ Copy failed: index.html not found in $REPO_NAME/"
            exit 1
          fi
          
          # Verify architecture page with diagrams was copied
          if [ -f "$REPO_NAME/architecture.html" ]; then
            echo "✅ Architecture page copied: $REPO_NAME/architecture.html"
            # Check file size (should be substantial if diagrams are included)
            FILE_SIZE=$(wc -c < "$REPO_NAME/architecture.html")
            echo "   File size: $FILE_SIZE bytes"
          else
            echo "⚠️  Warning: architecture.html not found in artifact"
          fi
          
          # Count total HTML files
          HTML_COUNT=$(find $REPO_NAME -name "*.html" | wc -l)
          echo "📄 Total HTML files in artifact: $HTML_COUNT"
          
          echo "✅ Artifact prepared: $REPO_NAME/index.html ready for deployment"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ github.event.repository.name }}

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        continue-on-error: true

      - name: Deployment info
        if: success()
        run: |
          REPO_NAME=$(echo ${{ github.repository }} | cut -d'/' -f2)
          echo ""
          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
          echo "✅ Deployment successful!"
          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
          echo ""
          echo "📄 Documentation Site:"
          echo "   https://${{ github.repository_owner }}.github.io/$REPO_NAME/"
          echo ""
          echo "📊 Architecture Page (with diagrams):"
          echo "   https://${{ github.repository_owner }}.github.io/$REPO_NAME/architecture.html"
          echo ""
          echo "⏱️  Wait 1-2 minutes for propagation, then clear cache if needed."
          echo ""
          echo "💡 Mermaid diagrams will render automatically via client-side JavaScript"
          echo ""

      - name: Check deployment status
        if: failure()
        run: |
          REPO_NAME=$(echo ${{ github.repository }} | cut -d'/' -f2)
          echo "::warning::Deployment failed. Enable GitHub Pages: Settings → Pages → Source: GitHub Actions"
          echo "Expected URL: https://${{ github.repository_owner }}.github.io/$REPO_NAME/"
          exit 1