fix(ci/docs): Separate build and deploy jobs for documentation

Refactor the GitHub Pages documentation workflow to explicitly separate the build and deployment phases into distinct jobs.

Previously, both build and deploy steps were part of a single `docs` job. This change introduces a dedicated `build` job to generate the MkDocs site and upload it as an artifact, and a `deploy` job to download this artifact and publish it to GitHub Pages.

This separation improves:
- **Clarity and maintainability:** Clearly delineates responsibilities for building versus deploying.
- **Robustness:** Ensures that the deployment logic, including the `if` condition for the `main` branch, is applied at the job level, preventing unintended deployments or permission issues.
- **Best practices:** Aligns with recommended GitHub Pages deployment patterns using `actions/configure-pages` and `actions/deploy-pages`.

This enhances the reliability and structure of the documentation deployment process.

Author: liblaf

template/.github/workflows/docs.yaml

@@ -14,22 +14,19 @@ on:
   workflow_dispatch:
 
 jobs:
-  docs:
-    name: Docs
-    permissions:
-      id-token: write
-      pages: write
+  build:
+    name: Build
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deploy.outputs.page_url }}
     steps:
       - name: Checkout
         uses: actions/checkout@v5
         with:
           fetch-depth: 0
-      - name: Configure GitHub Pages
+      - id: config
+        name: Configure GitHub Pages
         uses: actions/configure-pages@v5
+      - name: Set Environment Variables
+        run: printf 'SITE_URL=%s\n' '${{ steps.config.outputs.base_url }}' >> "$GITHUB_ENV"
       - name: Setup Python
         uses: liblaf/actions/setup-python@v1
       - if: hashFiles('docs/scripts/pre-build.sh') != ''
@@ -41,7 +38,20 @@ jobs:
         uses: actions/upload-pages-artifact@v4
         with:
           path: site
+
+  deploy:
+    name: Deploy
+    permissions:
+      id-token: write
+      pages: write
+    needs:
+      - build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
       - id: deploy
-        if: ${{ github.ref == 'refs/heads/main' }}
         name: Deploy Github Pages Site
         uses: actions/deploy-pages@v4