feat(site): rebuild the index site on the xpkgindex framework — fixes #170

.github/workflows/deploy-site.yml

@@ -10,6 +10,11 @@ on:
     paths:
       - 'pkgs/**'
       - '.xpkgindex.json'
+      # The plugin decides how every package reads, the docs are rendered as
+      # site pages, and the cache is what an offline build renders from — a
+      # change to any of them changes the site as much as a descriptor does.
+      - '.xpkgindex/**'
+      - 'docs/**'
       - '.github/workflows/deploy-site.yml'
   workflow_dispatch:
 
@@ -30,13 +35,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          # The growth curve, the history line and the contributor list are
+          # replayed from the git log. xpkgindex detects a shallow clone and
+          # skips all three with a warning, so the default depth of 1 was
+          # quietly shipping a site with no curve at all.
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
       - name: Install xpkgindex
         run: pip install git+https://github.com/openxlings/xpkgindex.git
       - name: Generate static site
         env:
+          # Raises the API rate limit and enables the author -> login mapping
+          # that merges one person's several git identities. The build works
+          # without it, with fewer avatars and less merging.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # xpkgindex >= Apr 2026 surfaces these on the About page.
           XPKGINDEX_BUILD_TIME:       ${{ github.event.head_commit.timestamp }}
           XPKGINDEX_BUILD_COMMIT:     ${{ github.sha }}

.github/workflows/refresh-site-cache.yml

@@ -0,0 +1,56 @@
+name: refresh-site-cache
+
+# Manual refresh of the data the site cannot read from `pkgs/` alone:
+# upstream repo metadata (stars, avatars, contributor logins) and, for Form A
+# packages, the upstream `mcpp.toml` that actually holds their build
+# information.
+#
+# Deliberately manual. The normal `deploy-site` build reads the committed
+# cache and touches no network, so a rendered page never depends on GitHub
+# being reachable at deploy time; this job is how new data gets in.
+#
+# Run it after adding a package or bumping one to a new upstream tag — the
+# cache is keyed by URL and a manifest URL contains the release tag, so a
+# bumped package fetches fresh while everything else is reused.
+
+on:
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "Why (shows up in the commit message)"
+        required: false
+        default: "manual refresh"
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # same reason as deploy-site: history replay
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install xpkgindex
+        run: pip install git+https://github.com/openxlings/xpkgindex.git
+
+      - name: Refresh cache
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: xpkgindex generate . --output /tmp/site --refresh
+
+      - name: Commit if anything changed
+        run: |
+          if git diff --quiet -- .xpkgindex/cache; then
+            echo "cache unchanged"
+            exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .xpkgindex/cache
+          git commit -m "chore(site): refresh upstream cache (${{ inputs.reason }})"
+          git push

.github/workflows/site-check.yml

@@ -0,0 +1,66 @@
+name: site-check
+
+# Builds the site on a pull request without publishing it. `validate.yml`
+# proves the packages compile; this proves they still render — a descriptor
+# that parses fine can still collide with another package's URL, and the
+# plugin reads fields no compiler checks.
+#
+# Deliberately offline: a pull request should not spend the API rate limit,
+# and the result should depend only on what is in the repository.
+
+on:
+  pull_request:
+    paths:
+      - 'pkgs/**'
+      - '.xpkgindex.json'
+      - '.xpkgindex/**'
+      - 'docs/**'
+      - '.github/workflows/site-check.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0        # --strict checks the replayed history against the tree
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install xpkgindex
+        run: pip install git+https://github.com/openxlings/xpkgindex.git
+
+      - name: Build the site
+        # --strict turns the growth reconciliation warning into an error: if
+        # the replayed history disagrees with the tree, the curve on the site
+        # would be wrong, and that is worth failing a pull request over.
+        run: xpkgindex generate . --output /tmp/site --offline --strict | tee /tmp/build.log
+
+      - name: No warnings
+        # A duplicate slug or an unparsable descriptor already fails above.
+        # Everything else the build is unhappy about arrives as a warning, and
+        # a warning nobody reads is a warning that becomes permanent.
+        run: |
+          if grep -q 'warning:' /tmp/build.log; then
+            echo "::error::the site build reported warnings"
+            grep 'warning:' /tmp/build.log
+            exit 1
+          fi
+
+      - name: The pages a reader lands on exist
+        run: |
+          set -e
+          for f in index.html index.json stats/index.html contributors/index.html \
+                   about/index.html docs/quick-start/index.html \
+                   zh/index.html zh-Hant/index.html; do
+            test -s "/tmp/site/$f" || { echo "::error::missing $f"; exit 1; }
+          done
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: site
+          path: /tmp/site
+          retention-days: 7

.gitignore

@@ -11,3 +11,6 @@ tests/examples/*/imgui.ini
 
 # 本地 git worktree(逐包验证时开的),不属于索引内容
 .worktrees/
+
+# plugin bytecode
+.xpkgindex/plugins/__pycache__/