From 4b28c075c2f5e0c9da9fe3a4202d157e43e2db62 Mon Sep 17 00:00:00 2001
From: Naruto TAKAHASHI <tnaruto@gmail.com>
Date: Fri, 10 Jul 2026 17:59:51 +0900
Subject: [PATCH] ci(docs): deploy Pages via artifact method, rename docs.yml
 -> pages.yml

Replace `mkdocs gh-deploy` (which pushes built HTML to a gh-pages branch)
with the GitHub Actions artifact deploy (upload-pages-artifact +
deploy-pages), matching SSPlayerForWeb / SSPlayerForRenPy. The workflow
file is renamed docs.yml -> pages.yml to match those repos as well.

- Drop contents:write; add pages:write + id-token:write
- Split into build + deploy jobs; PRs still validate with
  `mkdocs build --strict` but skip artifact upload / deploy
- Remove fetch-depth:0 and git-credential setup (only gh-deploy needed them)
- Only the MkDocs site/ output is served (no examples/demos to bundle)

Requires switching Settings > Pages > Source to "GitHub Actions" after merge.
---
 .github/workflows/docs.yml  | 66 -------------------------------
 .github/workflows/pages.yml | 79 +++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 66 deletions(-)
 delete mode 100644 .github/workflows/docs.yml
 create mode 100644 .github/workflows/pages.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
deleted file mode 100644
index 85e9b67..0000000
--- a/.github/workflows/docs.yml
+++ /dev/null
@@ -1,66 +0,0 @@
-name: Publish docs via GitHub Pages
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
-      - '.github/workflows/docs.yml'
-  pull_request:
-    paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
-      - '.github/workflows/docs.yml'
-  workflow_dispatch:
-
-# Needed by `mkdocs gh-deploy` to push the built site to the gh-pages branch.
-# Fork PRs receive a read-only token regardless; the deploy step is skipped for PRs anyway.
-permissions:
-  contents: write
-
-# Never let two doc builds push to gh-pages at the same time.
-concurrency:
-  group: docs-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-python@v6
-        with:
-          python-version: 3.x
-          cache: pip
-          cache-dependency-path: docs/requirements.txt
-
-      - run: echo "cache_id=$(date --utc '+%V')" >> "$GITHUB_ENV"
-
-      - uses: actions/cache@v5
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-
-      - name: Install dependencies
-        run: pip install -r docs/requirements.txt
-
-      # Fail the build on broken links / missing nav entries so PRs catch it before merge.
-      - name: Build docs (strict validation)
-        run: mkdocs build --strict
-
-      - name: Configure Git Credentials
-        if: github.event_name != 'pull_request'
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-
-      - name: Deploy docs
-        if: github.event_name != 'pull_request'
-        run: mkdocs gh-deploy --force
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..ab1d296
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,79 @@
+name: Publish docs via GitHub Pages
+
+# Build the MkDocs site and deploy it to GitHub Pages via the artifact method
+# (no gh-pages branch) — matching SSPlayerForWeb / SSPlayerForRenPy.
+#
+# Triggers stay on the docs hot path: push to main and manual dispatch deploy,
+# while PRs only build with --strict to catch broken links / nav gaps.
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/pages.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+# Permissions required by the artifact-based Pages deploy. No contents:write —
+# the gh-pages branch is gone.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Serialize deploys per ref; cancel only superseded PR builds, never a main deploy.
+concurrency:
+  group: docs-pages-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> "$GITHUB_ENV"
+
+      - uses: actions/cache@v5
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      # Fail the build on broken links / missing nav entries so PRs catch it before merge.
+      - name: Build docs (strict validation)
+        run: mkdocs build --strict
+
+      # Only the MkDocs output (site/) is served — no examples/demos to bundle.
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5