docs.yml

name: docs
on:
  push:
    branches: [master]
    paths:       
      - "docs/**"
      - "mkdocs.yml"
  workflow_dispatch: {}     

jobs:
  deploy:
    runs-on: ubuntu-24.04
    permissions:
      contents: write         
      pages: write            
    steps:
      # 1. Checkout full history so mkdocs can create gh-pages
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0     

      # 2. Install Python + MkDocs + theme
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: |
          pip install \
            mkdocs-material \
            mkdocs-git-revision-date-localized-plugin

      # 3. Configure git user (required for gh-deploy in CI)
      - run: |
          git config --global user.email "actions@github.com"
          git config --global user.name  "GitHub Actions"

      # 4. Build & push to gh-pages (force overwrite)
      - run: mkdocs gh-deploy --clean --force --verbose