docs-github-pages-publish.yml

name: Docs GitHub Pages Publish

on:
  push:
    branches:
      - main
      - master
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - "docs/requirements-mkdocs.txt"
      - "scripts/run-mkdocs.js"
      - "package.json"
      - "package-lock.json"
      - "README.md"
      - ".github/workflows/docs-github-pages-publish.yml"
  workflow_dispatch:
    inputs:
      git_ref:
        description: "Branch, tag, or commit to publish from (rollback)"
        required: false
        type: string
      site_url:
        description: "MkDocs site_url override"
        required: false
        default: "https://jacobinwwey.github.io/NoteConnection/"
        type: string
      base_path:
        description: "MkDocs base path override"
        required: false
        default: "/NoteConnection/"
        type: string

permissions:
  contents: write

concurrency:
  group: docs-github-pages
  cancel-in-progress: false

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
  verify-diataxis-map:
    name: verify-diataxis-map
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.git_ref != '' && github.event.inputs.git_ref || github.ref }}
          lfs: false

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Verify Diataxis mapping governance
        run: npm run docs:diataxis:check

  build-site:
    name: build-site
    runs-on: ubuntu-latest
    needs: verify-diataxis-map

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.git_ref != '' && github.event.inputs.git_ref || github.ref }}
          lfs: false

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: "pip"
          cache-dependency-path: docs/requirements-mkdocs.txt

      - name: Install MkDocs dependencies
        run: pip install -r docs/requirements-mkdocs.txt

      - name: Resolve MkDocs runtime URL config
        shell: bash
        run: |
          SITE_URL="${{ github.event_name == 'workflow_dispatch' && github.event.inputs.site_url || '' }}"
          BASE_PATH="${{ github.event_name == 'workflow_dispatch' && github.event.inputs.base_path || '' }}"
          if [ -z "${SITE_URL}" ]; then
            SITE_URL="https://jacobinwwey.github.io/NoteConnection/"
          fi
          if [ -z "${BASE_PATH}" ]; then
            BASE_PATH="/NoteConnection/"
          fi
          echo "MKDOCS_SITE_URL=${SITE_URL}" >> "$GITHUB_ENV"
          echo "MKDOCS_BASE_PATH=${BASE_PATH}" >> "$GITHUB_ENV"
          echo "MKDOCS_DOCS_HOST=https://jacobinwwey.github.io/" >> "$GITHUB_ENV"
          echo "site_url=${SITE_URL}" >> "$GITHUB_OUTPUT"
          echo "base_path=${BASE_PATH}" >> "$GITHUB_OUTPUT"

      - name: Build docs site
        run: mkdocs build --config-file mkdocs.yml

      - name: Preflight GitHub Pages enablement check
        shell: bash
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          PAGES_API="https://api.github.com/repos/${{ github.repository }}/pages"
          STATUS_CODE="$(curl -sS -o /tmp/pages-site.json -w '%{http_code}' \
            -H 'Accept: application/vnd.github+json' \
            -H "Authorization: Bearer ${GITHUB_TOKEN}" \
            "${PAGES_API}")"

          if [ "${STATUS_CODE}" = "404" ]; then
            echo "::warning::GitHub Pages site is not enabled yet for this repository. CI can still publish gh-pages branch, but https://jacobinwwey.github.io/NoteConnection/ will stay 404 until Settings -> Pages is configured to Deploy from branch (gh-pages / root)."
          elif [ "${STATUS_CODE}" -ge 200 ] && [ "${STATUS_CODE}" -lt 300 ]; then
            echo "GitHub Pages site API is available (HTTP ${STATUS_CODE})."
          else
            echo "::warning::Unable to verify GitHub Pages site state (HTTP ${STATUS_CODE})."
          fi

      - name: Deploy docs to gh-pages branch
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: build/mkdocs-site
          publish_branch: gh-pages
          force_orphan: true
          commit_message: "docs: publish site from ${{ github.sha }}"