Reset repo to deploy shell for Starlight docs migration (sourcebans-pp#1333) (#54)

Author: rumblefrog

.gitattributes

@@ -1,55 +1,119 @@
-name: Build and Deploy
+# SourceBans++ docs deploy workflow (cutover deliverable for issue #1333).
+#
+# This repo is the GitHub Pages deploy target for <https://sbpp.github.io/>.
+# The docs source lives in `sbpp/sourcebans-pp` under `docs/` (Astro Starlight);
+# this workflow checks that repo out, builds the site, and publishes via
+# GitHub's first-party `actions/deploy-pages`.
+#
+# Triggers:
+#   - repository_dispatch (event type: docs-changed) — fired by
+#     `.github/workflows/docs-deploy-trigger.yml` in `sbpp/sourcebans-pp` after a
+#     push to main that touches `docs/**`. The dispatcher mints a short-lived
+#     installation token via the org-owned `sbpp-docs-deploy` GitHub App
+#     (Actions: write scope on this repo only) so we never need a PAT.
+#   - workflow_dispatch — manual button in the Actions UI for forced redeploys.
+#   - schedule (weekly Sunday) — safety net in case a dispatch is dropped, the
+#     upstream source is unreachable at dispatch time, or a previous deploy
+#     failed silently.
+#
+# MANUAL SETUP REQUIRED (see issue #1333 cutover steps; cannot be configured in
+# workflow YAML):
+#   - Settings → Pages → Source must be set to "GitHub Actions" (UI-only).
+#   - The `sbpp-docs-deploy` GitHub App must exist with `Actions: write` scope on
+#     this repo, be installed on this repo, and have its App ID + private key
+#     registered as `vars.DOCS_DEPLOY_APP_ID` + `secrets.DOCS_DEPLOY_APP_KEY` in
+#     `sbpp/sourcebans-pp` (consumed by the dispatcher there — not by anything
+#     here).
+
+name: Deploy docs to Pages
 
 on:
-  push:
-    branches:
-      - main
+  repository_dispatch:
+    types: [docs-changed]
   workflow_dispatch:
+  schedule:
+    # Weekly safety net at Sunday 05:17 UTC. Non-zero minute avoids GitHub's
+    # top-of-hour cron congestion (per their scheduled-events docs).
+    - cron: '17 5 * * 0'
 
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
 
+# Allow only one concurrent deployment, but never cancel an in-flight one —
+# Pages deploys should always finish to avoid leaving the site in a
+# half-published state. Standard `actions/deploy-pages` convention.
+#
+# Group name matches the issue #1333 §6 spec (`pages-deploy`) rather than
+# GitHub's example default (`pages`). Since this is the only workflow in
+# this repo that touches Pages, either choice serializes the same set of
+# runs — we just track the spec verbatim so the cross-repo intent is
+# obvious to anyone diffing the cutover.
 concurrency:
   group: pages-deploy
   cancel-in-progress: false
 
 jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    env:
-      HUGO_VERSION: 0.88.1
+  build-and-deploy:
+    # Pinned (not `ubuntu-latest`) to match sibling
+    # `sbpp/sourcebans-pp/.github/workflows/docs-build.yml` so the build
+    # validation gate and the deploy run on byte-identical runner images.
+    runs-on: ubuntu-24.04
+    # Belt-and-suspenders against an upstream npm/Astro hang. Sibling
+    # `docs-screenshots.yml` uses 30; the deploy is build-only (no
+    # docker-compose / Playwright), so 15 is comfortably above the
+    # observed steady-state runtime.
+    timeout-minutes: 15
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # All `run:` steps below operate inside `docs/`. `cache-dependency-path`
+    # and `path:` inputs to `uses:` actions stay rooted at the workspace
+    # because action inputs are interpreted relative to the workspace, not
+    # the job's `working-directory` default.
+    defaults:
+      run:
+        working-directory: docs
+
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Checkout sourcebans-pp (docs source)
+        # Precedence: dispatched runs (repository_dispatch from
+        # `sourcebans-pp/.github/workflows/docs-deploy-trigger.yml`)
+        # carry the source commit SHA in the client payload — pin to it
+        # so two pushes A, B in quick succession don't race (A's deploy
+        # would otherwise check out main and silently rebuild from B).
+        # workflow_dispatch and schedule have no payload, so they fall
+        # through to the floating `main` ref by design (manual reruns
+        # and the weekly safety net both want the latest).
+        uses: actions/checkout@v5
         with:
-          submodules: true
-          fetch-depth: 0
+          repository: sbpp/sourcebans-pp
+          ref: ${{ github.event.client_payload.source_sha || 'main' }}
 
       - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: lts/*
-
-      - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v3
+        uses: actions/setup-node@v5
         with:
-          hugo-version: ${{ env.HUGO_VERSION }}
+          # Match sibling `sourcebans-pp/.github/workflows/docs-build.yml`
+          # and the documented floor in `sourcebans-pp/docs/README.md`
+          # ("Node 20 LTS or newer"). Asymmetry between the validation
+          # gate and the deploy would mean a build that passes CI could
+          # still fail here.
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
 
       - name: Install dependencies
-        run: |
-          npm install -g grunt-cli yarn
-          yarn set version latest
-          yarn install --no-lockfile
-
-      - name: Build content index
-        run: grunt content-index
+        run: npm ci
 
       - name: Build site
-        run: hugo --minify
+        run: npm run build
 
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./public
-          publish_branch: master
+          path: docs/dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/deploy.yml

@@ -45,10 +45,3 @@ Temporary Items
 
 # Netbeans
 /nbproject/
-
-# Dependencies
-node_modules
-
-# Hugo
-public
-dev

.gitignore

@@ -1,19 +1,18 @@
-# SourceBans++ Website [![Build and Deploy](https://github.com/sbpp/sbpp.github.io/actions/workflows/deploy.yml/badge.svg?branch=src)](https://github.com/sbpp/sbpp.github.io/actions/workflows/deploy.yml)
+# SourceBans++ Docs (deploy shell)
 
-### Adding Articles
+This repository is the GitHub Pages deploy target for the SourceBans++ documentation site at <https://sbpp.github.io/>.
 
-- Fork this repository
-- From Hugo CLI, generate appropriate kind of article using the archetypes provided, to the corresponding folder
-- Fill in the front matter and content
-- Submit pull request
+**Source lives in [`sbpp/sourcebans-pp` under `docs/`](https://github.com/sbpp/sourcebans-pp/tree/main/docs).** Open PRs there.
 
-### Contribute to Translation
+Pages is configured to build from GitHub Actions (Settings → Pages → Source: GitHub Actions). The workflow in `.github/workflows/deploy.yml` checks out `sourcebans-pp@main`, builds `docs/`, and deploys via `actions/deploy-pages`. It runs on `repository_dispatch` from `sourcebans-pp` (event type `docs-changed`), on `workflow_dispatch`, and on a weekly schedule as a safety net.
 
-- Fork this repository
-- Translate the files in `content/` by making another copy of the article and appending to the extension
-  - Ex: `content/docs/updating.md` -> `content/docs/updating.fr.md`
-  - You may also explicitly set `translationKey` in front matter within the article for good measures
-- Create a new block within `config.toml` adding the language translations for the global variables
-- Submit pull request
+## Local preview
 
-##### For more information, view [Hugo's Documentation](https://gohugo.io/documentation/)
+To preview the docs locally, clone `sourcebans-pp` and run the Starlight dev server:
+
+```sh
+git clone https://github.com/sbpp/sourcebans-pp.git
+cd sourcebans-pp/docs
+npm install
+npm run dev
+```