hd-garden 0.3.7 → 0.3.8

package/.env.example

@@ -8,11 +8,14 @@ ADMIN_URL=https://admin.example.com
 # 可选：反向代理或多域名后台时，显式指定 GitHub OAuth 回调地址。
 # GITHUB_OAUTH_REDIRECT_URI=https://admin.example.com/api/auth/github/callback
 
-# Giscus：在 https://giscus.app 配置后复制以下四项。
-GISCUS_REPO=owner/repository
-GISCUS_REPO_ID=R_xxxxxxxxxx
-GISCUS_CATEGORY=Announcements
-GISCUS_CATEGORY_ID=DIC_xxxxxxxxxx
+# 评论默认关闭。打开 https://giscus.app/zh-CN 安装后，去掉注释并填入真实值。
+# 仓库必须是 owner/name 这种公开仓库，且已开启 Discussions。
+# 线上还要把同名四项写进 GitHub Actions Variables。留空会让发布失败。
+# 确定不开放评论时，把 Actions Variable GISCUS_DISABLED 设为 1。
+# GISCUS_REPO=
+# GISCUS_REPO_ID=
+# GISCUS_CATEGORY=
+# GISCUS_CATEGORY_ID=
 
 # Webmention.io：注册正式域名后填写域名，不含 https://。
 WEBMENTION_IO_DOMAIN=example.com

package/Makefile

@@ -26,7 +26,6 @@ skill:
 
 prepare:
 	@if [ ! -d node_modules ]; then npm ci; fi
-	@if [ ! -f .env.local ]; then cp .env.example .env.local; fi
 
 dev: prepare
 	node bin/garden.mjs dev

package/README.md

@@ -55,11 +55,11 @@ make update    # 检查、提交并触发自动发布
 make update MESSAGE="新增一篇文章"
 ```
 
-`make dev` 会在首次运行时自动安装依赖并创建 `.env.local`。`make update` 会先检查，再提交并推送工作区中的所有改动。不想发布的文件请先移出仓库或加入 `.gitignore`。
+`make dev` 会在首次运行时自动安装依赖并创建 `.env.local`，同时说明如何接上评论。线上发布要求 Actions Variables 里有 `GISCUS_REPO`、`GISCUS_REPO_ID`、`GISCUS_CATEGORY`、`GISCUS_CATEGORY_ID`；留空会让构建失败。确定不开放评论时设置 `GISCUS_DISABLED=1`。`make update` 会先检查，再提交并推送工作区中的所有改动。不想发布的文件请先移出仓库或加入 `.gitignore`。
 
 ## 进一步配置
 
-首次跑通以后，再按需查看：
+评论接法见[从零开始](docs/quick-start.md)。跑通以后，再按需查看：
 
 - [评论、Webmentions 与内容分发](docs/integrations.md)
 - [随想管理后台](docs/admin-service.md)

package/app/components/Comments.tsx

@@ -1,29 +1,9 @@
 import { ChatCircle, GithubLogo } from "@phosphor-icons/react/ssr";
-import {
-  GiscusComments,
-  type GiscusConfig,
-} from "./GiscusComments";
-
-function giscusConfig(): GiscusConfig | undefined {
-  const config = {
-    repo:
-      process.env.GISCUS_REPO ?? process.env.NEXT_PUBLIC_GISCUS_REPO,
-    repoId:
-      process.env.GISCUS_REPO_ID ?? process.env.NEXT_PUBLIC_GISCUS_REPO_ID,
-    category:
-      process.env.GISCUS_CATEGORY ??
-      process.env.NEXT_PUBLIC_GISCUS_CATEGORY,
-    categoryId:
-      process.env.GISCUS_CATEGORY_ID ??
-      process.env.NEXT_PUBLIC_GISCUS_CATEGORY_ID,
-  };
-  return Object.values(config).every(Boolean)
-    ? (config as GiscusConfig)
-    : undefined;
-}
+import { readGiscusConfig } from "../lib/giscus-config";
+import { GiscusComments } from "./GiscusComments";
 
 export function Comments({ slug }: { slug: string }) {
-  const config = giscusConfig();
+  const config = readGiscusConfig();
 
   return (
     <section className="comments" aria-labelledby={`comments-heading-${slug}`}>
@@ -34,7 +14,7 @@ export function Comments({ slug }: { slug: string }) {
           <p>
             {config
               ? "评论由 GitHub Discussions 保存和管理。"
-              : "评论接入已准备好，补充 GitHub Discussions 配置后即可开放。"}
+              : "评论还没开放。配好下面四项后，这里才会出现评论框。"}
           </p>
         </div>
       </div>
@@ -45,8 +25,14 @@ export function Comments({ slug }: { slug: string }) {
         <div className="integration-notice">
           <GithubLogo size={20} weight="fill" />
           <p>
-            需要一个公开 GitHub 仓库，并为它启用 Discussions、安装 Giscus
-            App、选择评论分类。
+            打开{" "}
+            <a href="https://giscus.app/zh-CN" target="_blank" rel="noreferrer">
+              Giscus
+            </a>
+            ，安装到一个已开启 Discussions 的公开仓库，把仓库、仓库 ID、分类、分类 ID
+            写入 <code>.env.local</code> 和 GitHub Actions Variables：
+            <code>GISCUS_REPO</code>、<code>GISCUS_REPO_ID</code>、
+            <code>GISCUS_CATEGORY</code>、<code>GISCUS_CATEGORY_ID</code>。
           </p>
         </div>
       )}

package/app/components/GiscusComments.tsx

@@ -2,12 +2,9 @@
 
 import { useEffect, useRef } from "react";
 
-export type GiscusConfig = {
-  repo: string;
-  repoId: string;
-  category: string;
-  categoryId: string;
-};
+import type { GiscusConfig } from "../lib/giscus-config";
+
+export type { GiscusConfig };
 
 function currentGiscusTheme() {
   return document.documentElement.dataset.theme === "dark" ? "dark" : "light";

package/app/globals.css

@@ -2934,6 +2934,17 @@ button {
   font-size: 11px;
 }
 
+.integration-notice a,
+.integration-notice code {
+  text-decoration: underline;
+  text-underline-offset: 0.18em;
+}
+
+.integration-notice code {
+  text-decoration: none;
+  font-family: var(--font-mono), ui-monospace, monospace;
+}
+
 .integration-status {
   margin: 22px 0 0;
   color: var(--muted);

package/app/lib/giscus-config.ts

@@ -0,0 +1,39 @@
+export type GiscusConfig = {
+  repo: string;
+  repoId: string;
+  category: string;
+  categoryId: string;
+};
+
+const PLACEHOLDERS = new Set([
+  "owner/repository",
+  "R_xxxxxxxxxx",
+  "DIC_xxxxxxxxxx",
+]);
+
+function configuredValue(
+  env: Record<string, string | undefined>,
+  primary: string,
+  fallback: string,
+) {
+  const value = (env[primary] ?? env[fallback] ?? "").trim();
+  if (!value || PLACEHOLDERS.has(value)) return undefined;
+  return value;
+}
+
+export function readGiscusConfig(
+  env: Record<string, string | undefined> = process.env,
+): GiscusConfig | undefined {
+  const repo = configuredValue(env, "GISCUS_REPO", "NEXT_PUBLIC_GISCUS_REPO");
+  const repoId = configuredValue(env, "GISCUS_REPO_ID", "NEXT_PUBLIC_GISCUS_REPO_ID");
+  const category = configuredValue(env, "GISCUS_CATEGORY", "NEXT_PUBLIC_GISCUS_CATEGORY");
+  const categoryId = configuredValue(
+    env,
+    "GISCUS_CATEGORY_ID",
+    "NEXT_PUBLIC_GISCUS_CATEGORY_ID",
+  );
+  if (!repo || !repoId || !category || !categoryId) return undefined;
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repo)) return undefined;
+  if (!repoId.startsWith("R_") || !categoryId.startsWith("DIC_")) return undefined;
+  return { repo, repoId, category, categoryId };
+}

package/bin/garden.mjs

@@ -88,11 +88,25 @@ function ensurePublic() {
   }
 }
 
+function printGiscusGuide() {
+  process.stdout.write(`评论默认关闭。发布前要接上自己的 Giscus，留空会让 GitHub Actions 构建失败：
+  1. 准备一个公开 GitHub 仓库，并开启 Discussions。公开源码仓库可以直接用；私有源码要另建一个公开仓库。
+  2. 打开 https://giscus.app/zh-CN ，安装 Giscus App，只授权这个仓库，并选一个分类。
+  3. 把仓库、仓库 ID、分类、分类 ID 写入 .env.local 的 GISCUS_REPO、GISCUS_REPO_ID、GISCUS_CATEGORY、GISCUS_CATEGORY_ID。
+  4. 在源码仓库 Settings → Secrets and variables → Actions → Variables 写入同样四项。
+示例值不会被当成已配置。确定不开放评论时，把 Actions Variable GISCUS_DISABLED 设为 1。
+`);
+}
+
 function ensureEnv() {
+  // CI injects the real values. Copying .env.example there would fill any
+  // unset key with a sample, which used to turn comments on for owner/repository.
+  if (process.env.GITHUB_ACTIONS === "true") return;
   const example = path.join(gardenPackageRoot, ".env.example");
   const local = path.join(siteRoot, ".env.local");
   if (!fs.existsSync(local) && fs.existsSync(example)) {
     fs.copyFileSync(example, local);
+    printGiscusGuide();
   }
 }
 
@@ -241,8 +255,10 @@ function initSite() {
   process.stdout.write("下一步：\n");
   process.stdout.write(`  cd ${destination}\n`);
   process.stdout.write("  npm install\n");
+  process.stdout.write("  按下面四步接上评论，再写文章\n");
   process.stdout.write("  make new TITLE=\"你好，世界\" SLUG=hello\n");
   process.stdout.write("  make dev\n");
+  printGiscusGuide();
 }
 
 function packagedSkills() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/templates/site/README.md

@@ -8,6 +8,8 @@ make new TITLE="你好，世界" SLUG=hello
 make dev
 ```
 
-第一次 `npx garden dev` 会补齐 Makefile 和 skill。Cursor / Codex 打开这个仓库后会读到 `.agents/skills/`。要更新 skill，再运行 `npx garden skill`。
+第一次 `npx garden dev` 会补齐 Makefile 和 skill，并创建 `.env.local`。Cursor / Codex 打开这个仓库后会读到 `.agents/skills/`。要更新 skill，再运行 `npx garden skill`。
+
+评论默认关闭。发布前打开 [Giscus](https://giscus.app/zh-CN)，把仓库、仓库 ID、分类、分类 ID 写入 `.env.local`，并在 GitHub Actions Variables 设置同名的 `GISCUS_REPO`、`GISCUS_REPO_ID`、`GISCUS_CATEGORY`、`GISCUS_CATEGORY_ID`。留空会让发布失败。确定不开放评论时，把 `GISCUS_DISABLED` 设为 `1`。
 
 升级引擎：把 `package.json` 里的 `hd-garden` 改到新版本，例如 `^0.4.0`，再运行 `npm install`。