pages.yml

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

name: Deploy Jekyll site to Pages

on:
  push:
    branches:
      - "development"    # Only run on development branch
    paths:
      - '**/*.md'
      - 'docs/**'
      - '.github/workflows/pages.yml'
  pull_request:
    types: [closed]
    branches:
      - development  # TODO: Change to main for production

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages-deployment-${{ github.ref }}"
  cancel-in-progress: false

jobs:
  # Sync job
  sync:
    runs-on: ubuntu-latest
    if: github.event_name == 'push'
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ref: development

      - name: Sync and commit documentation
        run: |
          # Create temporary backup directory
          mkdir -p temp_backup

          # List of files/directories to preserve
          PRESERVE_FILES=(
            ".gitignore"
            "_config.yml"
            "_layouts"
            "_saas"
            "Gemfile"
            "just-the-docs.gemspec"
            "Dockerfile"
            "docker-compose.yml"
            "favicon.ico"
            "LICENSE"
          )

          # Backup all important files
          for item in "${PRESERVE_FILES[@]}"; do
            if [ -e "docs/$item" ]; then
              mkdir -p "temp_backup/$(dirname "$item")"
              cp -r "docs/$item" "temp_backup/$item"
            fi
          done

          # Clean the docs directory
          rm -rf docs/core docs/extensions docs/plugins docs/reports docs/services
          rm -f docs/*.md

          # Restore preserved files
          for item in "${PRESERVE_FILES[@]}"; do
            if [ -e "temp_backup/$item" ]; then
              mkdir -p "docs/$(dirname "$item")"
              cp -r "temp_backup/$item" "docs/$item"
            fi
          done

          # Clean up temporary backup
          rm -rf temp_backup

          # Create base docs directory if it doesn't exist
          mkdir -p docs

          # Function to add Jekyll front matter and copy file
          add_front_matter_and_copy() {
            local src="$1"
            local dst="$2"
            local title=$(basename "$src" .md)
            local rel_path=${dst#docs/}
            local parent_dir=$(dirname "$rel_path")
            
            # Convert path to nav section
            if [ "$parent_dir" = "." ]; then
              nav_section=""
            else
              nav_section="nav_section: ${parent_dir}"
            fi
            
            # Create front matter
            {
              echo "---"
              echo "layout: default"
              echo "title: ${title}"
              if [ ! -z "$nav_section" ]; then
                echo "$nav_section"
              fi
              echo "---"
              echo
              cat "$src"
            } > "$dst"
          }

          # Copy and process root level MD files
          find . -maxdepth 1 -name "*.md" -not -path "./docs/*" | while read src_file; do
            dst_file="docs/$(basename "$src_file")"
            add_front_matter_and_copy "$src_file" "$dst_file"
          done
          
          # For each main directory
          for dir in core extensions plugins reports services; do
            if [ -d "./$dir" ]; then
              find "./$dir" -type f -name "*.md" | while read src_file; do
                rel_path=${src_file#./$dir/}
                target_dir="docs/$dir/$(dirname "$rel_path")"
                target_file="$target_dir/$(basename "$rel_path")"
                mkdir -p "$target_dir"
                add_front_matter_and_copy "$src_file" "$target_file"
              done
            fi
          done
      - name: Upload the directory as an artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: docs

  # Build job
  build:
    runs-on: ubuntu-latest
    needs: sync
    steps:
      - name: Download the artifact
        uses: actions/download-artifact@v5
        with:
          name: docs
          path: docs
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true
          cache-version: 0
          working-directory: docs/
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Copy README to index.md
        run: cp README.md index.md
        working-directory: docs/
      - name: Build with Jekyll
        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
        env:
          JEKYLL_ENV: production
        working-directory: docs/
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/_site/

  # Deployment job
  deploy:
    needs: build
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4