hd-garden 0.8.0 → 0.8.2

package/templates/skills-en/garden-interactive-chart/references/style.md

@@ -0,0 +1,61 @@
+# Garden chart visuals
+
+Follow the tokens in the site's `app/globals.css`, not the dark green glow of whatever article you are referencing.
+
+## Tokens
+
+```css
+:root {
+  --paper: #f8f8f6;
+  --paper-deep: #eeeeeb;
+  --card: #ffffff;
+  --ink: #202124;
+  --ink-soft: #34383d;
+  --muted: #65707d;
+  --faint: #a1a6ad;
+  --line: #deded9;
+  --line-strong: #c9c9c2;
+  --accent: #d82d48;
+  --accent-soft: #f9e8eb;
+  --new: #1f7a4d;
+  --new-soft: #e5f4ec;
+}
+
+:root[data-theme="dark"] {
+  --paper: #171819;
+  --paper-deep: #202224;
+  --card: #1e2022;
+  --ink: #ededeb;
+  --ink-soft: #d8d8d4;
+  --muted: #a6adb6;
+  --faint: #747b84;
+  --line: #35383b;
+  --line-strong: #4b4f54;
+  --accent: #ff5d76;
+  --accent-soft: #3b242a;
+  --new: #5ee0a0;
+  --new-soft: #1a3a2c;
+}
+```
+
+Use the accent on one or two focal points at most. Newly computed uses `--new`, waste or repetition uses `--accent`, cached uses `--muted`.
+
+## Type and density
+
+```css
+font-family: ui-monospace, "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+font-size: 13px;
+line-height: 1.5;
+```
+
+Do not add Google Fonts. The text column is about 700px wide; draw for 640–680. Use multiples of 4 for control heights and spacing. No shadows, no large radii (4px at most on cells).
+
+## Semantic colors
+
+| Marker | Use |
+| --- | --- |
+| `new` / `append` | Cells newly computed at this beat |
+| `waste` | Past tokens that are recomputed |
+| `cached` | Read from the cache, not projected again |
+| `idle` | Placeholder, visually gone |
+| `repeat` / `unique` | Repeated vs unique in an inspect grid |

package/templates/skills-en/garden-post-review/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: garden-post-review
+description: >-
+  Reviews one specified Garden post in three steps: fix script-reported
+  structure errors, fix widgets with the chart skill, then suggest prose
+  improvements without editing. Use when the user asks to review or
+  proofread a Garden blog post.
+---
+
+# Review a Garden post
+
+Review only the post the user named. Do the three steps in order; each step sees the post as the previous step left it.
+
+Before you start, run `npx garden ui scan content/posts/path.md`. If any block has `status` `uncompiled`, `stale` or `error`, handle it with [garden-ui](../garden-ui/SKILL.md) first, then go to step 1.
+
+Hard check command (from the site root):
+
+```bash
+npx garden check content/posts/path.md
+```
+
+stdout is JSON. It passes only when `ok` is true. Do not re-check titles, dates or the reference list yourself.
+
+## 1. The script reports errors; fix only those
+
+Run `garden check`. If there are `errors`, change only those entries, then run the same command again until `ok` is true.
+
+- Touch only the places the errors point to.
+- Do not fix structural issues the script did not report.
+- `references` is recommended further reading. It does not have to match the links in the body one to one. Do not add an entry because the body has a link, and do not remove one because the body never mentions it.
+- `reference-heading`: move the flagged reference-list heading into `references` and delete the heading.
+- If a widget file is missing, only fix a mistyped `src`. Do not build a new chart in this step.
+
+## 2. Review and fix charts with the chart skill
+
+Do this step only when the post has a `widget`. Read [garden-interactive-chart](../garden-interactive-chart/SKILL.md) first.
+
+You may change the HTML in the same-name directory and the `caption` of its fence. Leave the surrounding prose alone. `caption` must be a one-sentence claim.
+
+Run `garden check` again afterwards, until it passes.
+
+Skip this step when there is no `widget`.
+
+## 3. Read the whole post; suggestions only
+
+`garden check` passes and the charts are fixed. Read the whole post. Do not change any file.
+
+There is one goal: does the post start from first principles, stay consistent, and close the loop on one point? After reading, the reader should be able to say what this is, why it has to be this way, and how that "why" lands in a piece of practice. Practice means code, an incident, a measurement, or a derivation put to work. It verifies the same chain; it is not a separate tutorial.
+
+First principles means reasoning up from facts, constraints or invariants that cannot be broken down further, not from "everyone does it this way" or a metaphor. After taking it apart, put it back together: listing the holes in existing approaches without reaching a conclusion is not finished. Analogies and industry practice may appear, but only as a foil for the derivation, never as a substitute for it.
+
+Write a suggestion only when:
+
+- The opening stands on a term, a convention or a metaphor, and the reader cannot see which fact constrains the problem
+- A later mechanism, term or conclusion cannot be derived from the earlier facts, or the same word means different things in different places
+- A point stops at "what it is": there is no why, or the why never lands in practice that can be checked
+- The practice and the principles talk past each other and are not the same chain
+- The post spreads across several neighbouring topics without bringing one of them home. One point explained fully beats many points touched lightly
+- Numbers, comparisons or "usually" claims do not grow out of the derivation, the practice or a source
+
+Each suggestion gives: the heading it is under, where the loop breaks, and how it could be closed. If there are none, say so. Do not turn the post into a problem–solution template, and do not ask for a "does not apply" note on every paragraph. If a translation already restates the original's derivation, do not ask the author to invent exercises.
+
+This step must not change the post, the charts or the front matter.

package/templates/skills-en/garden-ui/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: garden-ui
+description: >-
+  Compiles the `garden` idea blocks in one Garden post into garden components
+  (garden interactive, or card / stat / compare / ... , or prose, or garden
+  html), fixes broken garden interactive blocks, and suggests where a post could
+  use interaction. Older intent / ui blocks are handled the same way. Use when
+  the user says compile this post / compile ideas / recompile <id> / where could
+  this post use interaction, or pastes a garden ui check fix prompt.
+---
+
+# Compile Garden interactive blocks
+
+The author writes a one-sentence idea in an unnamed `garden` fence. This skill turns it into `garden interactive` or another `garden` component. The interactive components and design rules are in the output of `npx garden ui prompt`. The purpose and examples of the 12 `garden` components are in `node_modules/hd-garden/templates/garden-blocks.md` (in the engine repo, `templates/garden-blocks.md`). Treat those two as the source of truth; never write components from memory.
+
+When the author commits, the pre-commit hook runs the same `npx garden ui check`. The commands you use to find blocks, write them back and self-check are the same ones that stop the author's commit.
+
+Run every command from the site root. If no post path was given, ask only for the path; do not scan the whole repo.
+
+## Triggers and scope
+
+| The user says | Blocks to handle |
+| --- | --- |
+| Compile this post: `<path>`, compile ideas | Blocks with status `uncompiled`, `stale` or `error` |
+| Recompile `<id>` | Only this block, whatever its status |
+| Pastes a `garden ui check` fix prompt | The blocks listed in the prompt |
+| Where could this post use interaction | Read-only suggestion mode, see the end; do not edit the post |
+
+## Workflow
+
+1. Scan:
+
+   ```bash
+   npx garden ui scan content/posts/path.md
+   ```
+
+   stdout is JSON. `lang` is `garden-idea` (an idea), `garden-interactive`, or the older `intent` / `ui`. Each block has `lang`, `id`, `status`, `startLine`, `hash` (hash of the whole fence, used as `--base` on write-back), `intentHash` (hash of the author's words), `intent` (the author's words), `caption`, `section` (the heading it sits under) and `diagnostics`. Do not find fences yourself with regular expressions.
+
+2. Read the rules:
+
+   ```bash
+   npx garden ui prompt
+   ```
+
+   It contains the component catalog, recipes and design rules. Follow the recipe skeletons; do not invent components or properties that are not in the catalog.
+
+3. For each block, read the author's words and its section, then pick one:
+   - **Write it back as prose**: when a sentence, a table or a Mermaid diagram says it clearly.
+   - **Write `garden interactive`**: when the reader needs to drag, click or step through it to understand.
+   - **Write a `diff`**: when the idea follows a complete code block and is about "what changed since the last version". Write the diff the words describe as plain Markdown (just this one `diff` fence). Once written back it sits right after that code, and the page turns them into a "code / compare with previous" toggle. New lines in the diff must match the complete code above.
+   - **Write another `garden` component**: one or more resource cards (`card` / `cards`), a few metrics (`stat`), two approaches side by side or a good/bad comparison (`compare` / `verdict: good|bad`), a timeline (`timeline`), a static chart (`chart`), a labelled structure diagram (`figure`), a downloadable file (`file`), a relationship diagram of 3–6 elements (`relations`), a compact icon list or step list (`list`), or a choice card with two or three options (`choice`). Fields and validation rules are in `npx garden ui prompt` and `templates/garden-blocks.md`.
+   - **Write `garden html`**: canvas animation, audio, physics simulations and anything else the catalog cannot express. Write the HTML in the same-name directory following [garden-interactive-chart](../garden-interactive-chart/SKILL.md), and put the claim in `title`.
+
+4. When writing `garden interactive`:
+   - Format: the fence header is `garden interactive #<id>`. Above `---` go `caption`, `intent` and an optional `expect`; below `---` goes the component tree from `npx garden ui prompt`.
+   - Put the author's words into `intent` verbatim; do not change a single character.
+   - `caption` takes the claim from the author's words. If there is no claim, write one from the section and say so in your reply.
+   - Known points in the words ("512 MiB at batch 1") go into `expect`.
+   - Data lives in the block. Use `Data` references only when the words mention a data file that already exists in the same-name directory.
+   - If a block gets too big, split it into two, each placed next to the paragraph it explains. Do not move it to another file.
+
+5. Write each block back with `apply`, passing the new content on standard input:
+
+   ````bash
+   npx garden ui apply content/posts/path.md --id <id> --base <hash> <<'GARDEN_UI'
+   ```garden interactive #id
+   caption: ...
+   intent: |
+     ...
+   ---
+   ...
+   ```
+   GARDEN_UI
+   ````
+
+   - Idea blocks have no id; locate them with `--intent-hash <intentHash>`, or `--at <startLine>` when the words repeat.
+   - The new content can be one `garden` component fence (interactive, card, stat, …) or plain Markdown (when writing it back as prose). Old `ui` blocks may also be written back in their original format.
+   - The new content must not contain any uncompiled ideas.
+   - On success stdout is `{"ok":true,...}`. On failure stderr is JSON; act on `code`:
+     - `apply-invalid`: the new content failed validation. Fix it from `diagnostics` and write again.
+     - `apply-base`: the block changed after the scan. Run `scan` again and use the new `hash`.
+     - `apply-not-found` / `apply-ambiguous`: the block was not found or not unique. Run `scan` again and locate it another way.
+   - Line numbers shift after each write-back, so run `scan` again before the next block.
+
+6. When everything is written:
+
+   ```bash
+   npx garden ui check content/posts/path.md
+   npx garden check content/posts/path.md
+   ```
+
+   The first is the pre-commit check and must pass; the second must report `ok` true. If the same block fails three times in a row, stop and report the diagnostics to the user as they are.
+
+7. Reply with a table:
+
+   | id | choice | recipe | assumptions | expect |
+   | --- | --- | --- | --- | --- |
+   | kv-memory | garden interactive | param bench | default sequence is 4K | 512 MiB at batch 1 |
+
+   "Assumptions" lists what the author's words did not say and you decided for them (defaults, ranges, an added caption). Write "none" if there are none.
+
+## Don't
+
+- Edit the post file directly. The post changes only through `apply`; HTML files referenced by `garden html` may be created directly.
+- Invent numbers the author did not give. If a number is needed and missing, compute it from a formula in the words or ask the author.
+- Use remote URLs (images, scripts, data).
+- Change prose outside the target blocks.
+
+## Suggestion mode: where could this post use interaction
+
+Read-only; do not edit the post. Run `npx garden ui prompt` to read the design rules, then read the whole post and pick paragraphs that plain text or a static image cannot explain well:
+
+- A formula or numbers that change with parameters (param bench, converter)
+- A multi-step process (stepper, flow)
+- The difference between two approaches (comparison)
+- A set of cells, bytes or a memory layout (grid)
+
+For each, give: the section, why text is not enough, and a draft `garden` idea block that can be pasted right after that paragraph. The draft says only what the reader does and sees, plus numbers already in the post; do not name components. Five at most; if none fit, say so.

package/templates/workflows/pages.en.yml

@@ -0,0 +1,195 @@
+name: Verify and publish blog
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-blog
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event.repository.name == format('{0}.github.io', github.repository_owner) || vars.SITE_URL != '' || vars.PAGES_REPOSITORY != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Resolve the public URL
+        env:
+          SITE_URL_OVERRIDE: ${{ vars.SITE_URL }}
+          ADMIN_URL_OVERRIDE: ${{ vars.ADMIN_URL }}
+          GISCUS_REPO: ${{ vars.GISCUS_REPO }}
+          GISCUS_REPO_ID: ${{ vars.GISCUS_REPO_ID }}
+          GISCUS_CATEGORY: ${{ vars.GISCUS_CATEGORY }}
+          GISCUS_CATEGORY_ID: ${{ vars.GISCUS_CATEGORY_ID }}
+          GISCUS_DISABLED: ${{ vars.GISCUS_DISABLED }}
+          WEBMENTION_IO_DOMAIN: ${{ vars.WEBMENTION_IO_DOMAIN }}
+          ANALYTICS_DOMAIN: ${{ vars.ANALYTICS_DOMAIN }}
+          ANALYTICS_SCRIPT: ${{ vars.ANALYTICS_SCRIPT }}
+        run: |
+          owner="$GITHUB_REPOSITORY_OWNER"
+          default_url="https://$owner.github.io"
+          giscus_ready=1
+          if [ -z "$GISCUS_REPO" ] || [ "$GISCUS_REPO" = "owner/repository" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_REPO_ID" ] || [ "$GISCUS_REPO_ID" = "R_xxxxxxxxxx" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_CATEGORY" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_CATEGORY_ID" ] || [ "$GISCUS_CATEGORY_ID" = "DIC_xxxxxxxxxx" ]; then giscus_ready=0; fi
+          if [ "$giscus_ready" != 1 ]; then
+            if [ "$GISCUS_DISABLED" = "1" ]; then
+              GISCUS_REPO=
+              GISCUS_REPO_ID=
+              GISCUS_CATEGORY=
+              GISCUS_CATEGORY_ID=
+              echo "GISCUS_DISABLED=1; building without comments."
+            else
+              echo "Comments are not configured yet; stopping the build."
+              echo "1. Prepare a public GitHub repository and enable Discussions."
+              echo "2. Open https://giscus.app, install the Giscus App, and pick the repository and category."
+              echo "3. Under Settings -> Secrets and variables -> Actions -> Variables, set:"
+              echo "   GISCUS_REPO, GISCUS_REPO_ID, GISCUS_CATEGORY, GISCUS_CATEGORY_ID"
+              echo "To build without comments, set GISCUS_DISABLED to 1. Empty values and the placeholder owner/repository will not pass."
+              exit 1
+            fi
+          fi
+          {
+            echo "SITE_URL=${SITE_URL_OVERRIDE:-$default_url}"
+            echo "NEXT_PUBLIC_SITE_URL=${SITE_URL_OVERRIDE:-$default_url}"
+            echo "ADMIN_URL=$ADMIN_URL_OVERRIDE"
+            echo "GISCUS_REPO=$GISCUS_REPO"
+            echo "GISCUS_REPO_ID=$GISCUS_REPO_ID"
+            echo "GISCUS_CATEGORY=$GISCUS_CATEGORY"
+            echo "GISCUS_CATEGORY_ID=$GISCUS_CATEGORY_ID"
+            echo "NEXT_PUBLIC_GISCUS_REPO=$GISCUS_REPO"
+            echo "NEXT_PUBLIC_GISCUS_REPO_ID=$GISCUS_REPO_ID"
+            echo "NEXT_PUBLIC_GISCUS_CATEGORY=$GISCUS_CATEGORY"
+            echo "NEXT_PUBLIC_GISCUS_CATEGORY_ID=$GISCUS_CATEGORY_ID"
+            echo "WEBMENTION_IO_DOMAIN=$WEBMENTION_IO_DOMAIN"
+            echo "NEXT_PUBLIC_ANALYTICS_DOMAIN=$ANALYTICS_DOMAIN"
+            echo "NEXT_PUBLIC_ANALYTICS_SCRIPT=$ANALYTICS_SCRIPT"
+            echo "STATIC_EXPORT=1"
+          } >> "$GITHUB_ENV"
+
+      - name: Build the public site
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: npm run build
+
+      - name: Validate the static output
+        run: npm run pages:validate
+
+      - name: Configure GitHub Pages
+        if: ${{ vars.PAGES_REPOSITORY == '' }}
+        uses: actions/configure-pages@v6
+
+      - name: Upload the GitHub Pages artifact
+        if: ${{ vars.PAGES_REPOSITORY == '' }}
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist/client
+
+      - name: Upload the public-repository artifact
+        if: ${{ vars.PAGES_REPOSITORY != '' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: static-site
+          path: dist/client
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+
+  deploy-pages:
+    if: ${{ vars.PAGES_REPOSITORY == '' }}
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy the GitHub Pages artifact
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  publish-repository:
+    if: ${{ vars.PAGES_REPOSITORY != '' }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Check the split-repository configuration
+        env:
+          PAGES_DEPLOY_KEY: ${{ secrets.PAGES_DEPLOY_KEY }}
+          TARGET_REPOSITORY: ${{ vars.PAGES_REPOSITORY }}
+        run: |
+          test -n "$PAGES_DEPLOY_KEY" || { echo "Missing PAGES_DEPLOY_KEY secret"; exit 1; }
+          [[ "$TARGET_REPOSITORY" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || {
+            echo "Invalid PAGES_REPOSITORY format"
+            exit 1
+          }
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: static-site
+          path: static-site
+
+      - name: Check out the public output repository
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ vars.PAGES_REPOSITORY }}
+          ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
+          path: pages-repository
+          fetch-depth: 1
+
+      - name: Start a clean rolling deployment
+        working-directory: pages-repository
+        env:
+          TARGET_REPOSITORY: ${{ vars.PAGES_REPOSITORY }}
+        run: |
+          expected_remote="git@github.com:$TARGET_REPOSITORY.git"
+          actual_remote="$(git remote get-url origin)"
+          test "$actual_remote" = "$expected_remote" || {
+            echo "Refusing to publish to unexpected repository: $actual_remote"
+            exit 1
+          }
+          echo "PAGES_PREVIOUS_TREE=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_ENV"
+          git checkout --orphan pages-deploy
+          git rm -q -r -f .
+
+      - name: Prepare generated-only repository contents
+        run: npx garden pages:prepare static-site pages-repository
+
+      - name: Publish the rolling deployment commit
+        working-directory: pages-repository
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          new_tree="$(git write-tree)"
+          if [ "$new_tree" = "$PAGES_PREVIOUS_TREE" ]; then
+            echo "Static output is unchanged; skipping publish"
+            exit 0
+          fi
+          git commit -m "Deploy ${GITHUB_SHA}"
+          git push --force origin HEAD:main

package/templates/workflows/pages.yml

@@ -0,0 +1,195 @@
+name: Verify and publish blog
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-blog
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event.repository.name == format('{0}.github.io', github.repository_owner) || vars.SITE_URL != '' || vars.PAGES_REPOSITORY != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Resolve the public URL
+        env:
+          SITE_URL_OVERRIDE: ${{ vars.SITE_URL }}
+          ADMIN_URL_OVERRIDE: ${{ vars.ADMIN_URL }}
+          GISCUS_REPO: ${{ vars.GISCUS_REPO }}
+          GISCUS_REPO_ID: ${{ vars.GISCUS_REPO_ID }}
+          GISCUS_CATEGORY: ${{ vars.GISCUS_CATEGORY }}
+          GISCUS_CATEGORY_ID: ${{ vars.GISCUS_CATEGORY_ID }}
+          GISCUS_DISABLED: ${{ vars.GISCUS_DISABLED }}
+          WEBMENTION_IO_DOMAIN: ${{ vars.WEBMENTION_IO_DOMAIN }}
+          ANALYTICS_DOMAIN: ${{ vars.ANALYTICS_DOMAIN }}
+          ANALYTICS_SCRIPT: ${{ vars.ANALYTICS_SCRIPT }}
+        run: |
+          owner="$GITHUB_REPOSITORY_OWNER"
+          default_url="https://$owner.github.io"
+          giscus_ready=1
+          if [ -z "$GISCUS_REPO" ] || [ "$GISCUS_REPO" = "owner/repository" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_REPO_ID" ] || [ "$GISCUS_REPO_ID" = "R_xxxxxxxxxx" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_CATEGORY" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_CATEGORY_ID" ] || [ "$GISCUS_CATEGORY_ID" = "DIC_xxxxxxxxxx" ]; then giscus_ready=0; fi
+          if [ "$giscus_ready" != 1 ]; then
+            if [ "$GISCUS_DISABLED" = "1" ]; then
+              GISCUS_REPO=
+              GISCUS_REPO_ID=
+              GISCUS_CATEGORY=
+              GISCUS_CATEGORY_ID=
+              echo "GISCUS_DISABLED=1，本次构建不开放评论。"
+            else
+              echo "评论还没有配置，构建已停止。"
+              echo "1. 准备一个公开 GitHub 仓库，并开启 Discussions。"
+              echo "2. 打开 https://giscus.app/zh-CN ，安装 Giscus App，选中该仓库和分类。"
+              echo "3. 在 Settings → Secrets and variables → Actions → Variables 写入："
+              echo "   GISCUS_REPO、GISCUS_REPO_ID、GISCUS_CATEGORY、GISCUS_CATEGORY_ID"
+              echo "确定不开放评论时，把 GISCUS_DISABLED 设为 1。留空和示例值 owner/repository 都不会通过。"
+              exit 1
+            fi
+          fi
+          {
+            echo "SITE_URL=${SITE_URL_OVERRIDE:-$default_url}"
+            echo "NEXT_PUBLIC_SITE_URL=${SITE_URL_OVERRIDE:-$default_url}"
+            echo "ADMIN_URL=$ADMIN_URL_OVERRIDE"
+            echo "GISCUS_REPO=$GISCUS_REPO"
+            echo "GISCUS_REPO_ID=$GISCUS_REPO_ID"
+            echo "GISCUS_CATEGORY=$GISCUS_CATEGORY"
+            echo "GISCUS_CATEGORY_ID=$GISCUS_CATEGORY_ID"
+            echo "NEXT_PUBLIC_GISCUS_REPO=$GISCUS_REPO"
+            echo "NEXT_PUBLIC_GISCUS_REPO_ID=$GISCUS_REPO_ID"
+            echo "NEXT_PUBLIC_GISCUS_CATEGORY=$GISCUS_CATEGORY"
+            echo "NEXT_PUBLIC_GISCUS_CATEGORY_ID=$GISCUS_CATEGORY_ID"
+            echo "WEBMENTION_IO_DOMAIN=$WEBMENTION_IO_DOMAIN"
+            echo "NEXT_PUBLIC_ANALYTICS_DOMAIN=$ANALYTICS_DOMAIN"
+            echo "NEXT_PUBLIC_ANALYTICS_SCRIPT=$ANALYTICS_SCRIPT"
+            echo "STATIC_EXPORT=1"
+          } >> "$GITHUB_ENV"
+
+      - name: Build the public site
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: npm run build
+
+      - name: Validate the static output
+        run: npm run pages:validate
+
+      - name: Configure GitHub Pages
+        if: ${{ vars.PAGES_REPOSITORY == '' }}
+        uses: actions/configure-pages@v6
+
+      - name: Upload the GitHub Pages artifact
+        if: ${{ vars.PAGES_REPOSITORY == '' }}
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist/client
+
+      - name: Upload the public-repository artifact
+        if: ${{ vars.PAGES_REPOSITORY != '' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: static-site
+          path: dist/client
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+
+  deploy-pages:
+    if: ${{ vars.PAGES_REPOSITORY == '' }}
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy the GitHub Pages artifact
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  publish-repository:
+    if: ${{ vars.PAGES_REPOSITORY != '' }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Check the split-repository configuration
+        env:
+          PAGES_DEPLOY_KEY: ${{ secrets.PAGES_DEPLOY_KEY }}
+          TARGET_REPOSITORY: ${{ vars.PAGES_REPOSITORY }}
+        run: |
+          test -n "$PAGES_DEPLOY_KEY" || { echo "缺少 PAGES_DEPLOY_KEY Secret"; exit 1; }
+          [[ "$TARGET_REPOSITORY" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || {
+            echo "PAGES_REPOSITORY 格式无效"
+            exit 1
+          }
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: static-site
+          path: static-site
+
+      - name: Check out the public output repository
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ vars.PAGES_REPOSITORY }}
+          ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
+          path: pages-repository
+          fetch-depth: 1
+
+      - name: Start a clean rolling deployment
+        working-directory: pages-repository
+        env:
+          TARGET_REPOSITORY: ${{ vars.PAGES_REPOSITORY }}
+        run: |
+          expected_remote="git@github.com:$TARGET_REPOSITORY.git"
+          actual_remote="$(git remote get-url origin)"
+          test "$actual_remote" = "$expected_remote" || {
+            echo "拒绝发布到非目标仓库：$actual_remote"
+            exit 1
+          }
+          echo "PAGES_PREVIOUS_TREE=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_ENV"
+          git checkout --orphan pages-deploy
+          git rm -q -r -f .
+
+      - name: Prepare generated-only repository contents
+        run: npx garden pages:prepare static-site pages-repository
+
+      - name: Publish the rolling deployment commit
+        working-directory: pages-repository
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          new_tree="$(git write-tree)"
+          if [ "$new_tree" = "$PAGES_PREVIOUS_TREE" ]; then
+            echo "静态产物没有变化，无需发布"
+            exit 0
+          fi
+          git commit -m "Deploy ${GITHUB_SHA}"
+          git push --force origin HEAD:main