hd-garden 0.3.7 → 0.3.9

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/blog/page.tsx

@@ -1,6 +1,7 @@
 import { Suspense } from "react";
 import { siteConfig, siteDocumentTitle } from "../site.config";
 import { BlogArchive } from "../components/BlogArchive";
+import { PageIntro } from "../components/PageIntro";
 
 export const metadata = {
   title: siteDocumentTitle,
@@ -10,11 +11,11 @@ export const metadata = {
 export default function BlogIndex() {
   return (
     <main className="page-shell index-page">
-      <header className="page-intro">
-        <p className="eyebrow">POSTS / 博文</p>
-        <h1>{siteConfig.pages.blog.title}</h1>
-        <p>{siteConfig.pages.blog.subtitle}</p>
-      </header>
+      <PageIntro
+        eyebrow="POSTS / 博文"
+        title={siteConfig.pages.blog.title}
+        subtitle={siteConfig.pages.blog.subtitle}
+      />
       <Suspense>
         <BlogArchive />
       </Suspense>

package/app/columns/page.tsx

@@ -53,7 +53,7 @@ export default function ColumnsPage() {
                 <p>
                   {first.columnDescription ??
                     first.description ??
-                    "沿着一条清晰的阅读路径，把一个主题持续写深。"}
+                    "按顺序组织的专题文章系列。"}
                 </p>
                 <strong>
                   从第一篇开始

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/ContentEmptyState.tsx

@@ -7,24 +7,24 @@ const emptyContent = {
   posts: {
     icon: Article,
     eyebrow: "NO POSTS YET / 暂无博文",
-    title: "这里还没有博文。",
-    description: "第一篇长文发布后，会从这里开始形成可检索、可归档的写作记录。",
+    title: "暂无博文。",
+    description: "发布文章后会在这里按主题与时间归档。",
     actionHref: "/",
     actionLabel: "返回首页",
   },
   thoughts: {
     icon: Quotes,
     eyebrow: "NO THOUGHTS YET / 暂无随想",
-    title: "随想还没有开始。",
-    description: "短句、照片、声音和临时冒出的念头，之后都会沿着时间线落在这里。",
+    title: "暂无随想。",
+    description: "日常的碎片记录、短笔记与链接会落在这里。",
     actionHref: "/blog",
     actionLabel: "先读博文",
   },
   columns: {
     icon: Books,
     eyebrow: "NO COLUMNS YET / 暂无专栏",
-    title: "专栏正在形成。",
-    description: "当同一主题积累出清晰的阅读顺序，这里会出现第一条连续的阅读路径。",
+    title: "暂无专栏。",
+    description: "文章积累成系列后会在这里按顺序呈现。",
     actionHref: "/blog",
     actionLabel: "浏览全部博文",
   },

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/fallback-site-config.ts

@@ -11,38 +11,38 @@ export const siteConfig = {
   },
   pages: {
     home: {
-      title: "把复杂的事，\n慢慢想明白。",
-      subtitle: "在这里记录产品、工程、学习与日常生活中值得慢慢想明白的事。",
+      title: "记一些正在做的事，\n和想清楚的问题。",
+      subtitle: "关注软件工程、系统设计与技术实践，也记录偶发的探索和工作笔记。",
     },
     blog: {
-      title: "长期写下去，偶尔回头整理。",
-      subtitle: "这里是完整文章：有明确主题、有持续论证，也允许自己在更新里修正旧判断。",
+      title: "博文",
+      subtitle: "阶段性的完整梳理与技术总结。",
     },
     thoughts: {
-      title: "不够写成文章的，也值得留下。",
-      subtitle: "私人朋友圈式的轻量记录：短文字、照片、声音、影像，以及偶然遇见的链接。",
+      title: "随想",
+      subtitle: "碎片的念头、偶遇的灵感、短笔记与链接。",
     },
     columns: {
-      title: "把一个主题，写到足够深入。",
-      subtitle: "专栏不是标签集合，而是一条有顺序的阅读路径。左侧章节导航会在阅读时始终陪着你。",
+      title: "专栏",
+      subtitle: "按顺序组织的专题系列，沿着清晰的脉络连点成线。",
     },
     about: {
       title: "你好，我是 Your Name。",
-      subtitle: "在这里写下你关心的问题、长期的方向，以及你希望如何与世界保持联系。",
-      heading: "这个网站为什么存在",
+      subtitle: "欢迎来到我的个人网站。",
+      heading: "关于我与这里",
       paragraphs: [
-        "我需要一个不被信息流推着走的地方。长文可以慢慢展开，随想可以轻轻放下；同一个主题也可以沿着清晰的顺序持续生长。",
-        "所有文章都从本地 Markdown 文件开始。这意味着我可以继续在 Typora 里写作，也意味着内容不会被某个编辑器或平台锁住。",
+        "一名工程师 / 创作者。平时主要关注系统开发、技术探索与软件设计。",
+        "这里是我的公开工作台与数字自留地。比起社交网络上的碎片动态，我更倾向于把探索过程沉淀为有据可查的代码、设计与长篇笔记。",
       ],
-      quote: "写作不是把已经想明白的东西记下来，而是在句子之间发现自己还没有想明白什么。",
+      quote: "",
       focus: [
-        "将自己的关注方向写在这里",
-        "用文章积累可迁移的知识",
-        "为长期写作留出稳定的空间",
+        "软件工程与系统架构",
+        "原生工具与高质量交互",
+        "个人长期知识沉淀",
       ],
       cta: {
         href: "/blog",
-        label: "从博文开始",
+        label: "浏览博文",
       },
     },
     garden: {
@@ -50,7 +50,7 @@ export const siteConfig = {
       subtitle: "",
     },
   },
-  footer: "保持独立，持续写作。",
+  footer: "持续记录与构建。",
 };
 
 export const githubUrl = `https://github.com/${siteConfig.author.github}`;

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.9",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/site.config.yaml

@@ -14,35 +14,35 @@ author:
 pages:
   home:
     title: |-
-      把复杂的事，
-      慢慢想明白。
-    subtitle: 在这里记录产品、工程、学习与日常生活中值得慢慢想明白的事。
+      记一些正在做的事，
+      和想清楚的问题。
+    subtitle: 关注软件工程、系统设计与技术实践，也记录偶发的探索和工作笔记。
   blog:
-    title: 长期写下去，偶尔回头整理。
-    subtitle: 这里是完整文章：有明确主题、有持续论证，也允许自己在更新里修正旧判断。
+    title: 博文
+    subtitle: 阶段性的完整梳理与技术总结。
   thoughts:
-    title: 不够写成文章的，也值得留下。
-    subtitle: 私人朋友圈式的轻量记录：短文字、照片、声音、影像，以及偶然遇见的链接。
+    title: 随想
+    subtitle: 碎片的念头、偶遇的灵感、短笔记与链接。
   columns:
-    title: 把一个主题，写到足够深入。
-    subtitle: 专栏不是标签集合，而是一条有顺序的阅读路径。左侧章节导航会在阅读时始终陪着你。
+    title: 专栏
+    subtitle: 按顺序组织的专题系列，沿着清晰的脉络连点成线。
   about:
     title: 你好，我是 Your Name。
-    subtitle: 在这里写下你关心的问题、长期的方向，以及你希望如何与世界保持联系。
-    heading: 这个网站为什么存在
+    subtitle: 欢迎来到我的个人网站。
+    heading: 关于我与这里
     paragraphs:
-      - 我需要一个不被信息流推着走的地方。长文可以慢慢展开，随想可以轻轻放下；同一个主题也可以沿着清晰的顺序持续生长。
-      - 所有文章都从本地 Markdown 文件开始。这意味着我可以继续在 Typora 里写作，也意味着内容不会被某个编辑器或平台锁住。
-    quote: 写作不是把已经想明白的东西记下来，而是在句子之间发现自己还没有想明白什么。
+      - 一名工程师 / 创作者。平时主要关注系统开发、技术探索与软件设计。
+      - 这里是我的公开工作台与数字自留地。比起社交网络上的碎片动态，我更倾向于把探索过程沉淀为有据可查的代码、设计与长篇笔记。
+    quote: ""
     focus:
-      - 将自己的关注方向写在这里
-      - 用文章积累可迁移的知识
-      - 为长期写作留出稳定的空间
+      - 软件工程与系统架构
+      - 原生工具与高质量交互
+      - 个人长期知识沉淀
     cta:
       href: /blog
-      label: 从博文开始
+      label: 浏览博文
   garden:
     title: 一个基于 Markdown 的个人博客框架。
     subtitle: ""
 
-footer: 保持独立，持续写作。
+footer: 持续记录与构建。

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`。

package/templates/site/site.config.yaml

@@ -12,35 +12,35 @@ author:
 pages:
   home:
     title: |-
-      把复杂的事，
-      慢慢想明白。
-    subtitle: 在这里记录产品、工程、学习与日常生活中值得慢慢想明白的事。
+      记一些正在做的事，
+      和想清楚的问题。
+    subtitle: 关注软件工程、系统设计与技术实践，也记录偶发的探索和工作笔记。
   blog:
-    title: 长期写下去，偶尔回头整理。
-    subtitle: 这里是完整文章：有明确主题、有持续论证，也允许自己在更新里修正旧判断。
+    title: 博文
+    subtitle: 阶段性的完整梳理与技术总结。
   thoughts:
-    title: 不够写成文章的，也值得留下。
-    subtitle: 私人朋友圈式的轻量记录：短文字、照片、声音、影像，以及偶然遇见的链接。
+    title: 随想
+    subtitle: 碎片的念头、偶遇的灵感、短笔记与链接。
   columns:
-    title: 把一个主题，写到足够深入。
-    subtitle: 专栏不是标签集合，而是一条有顺序的阅读路径。
+    title: 专栏
+    subtitle: 按顺序组织的专题系列，沿着清晰的脉络连点成线。
   about:
     title: 你好，我是 Your Name。
-    subtitle: 在这里写下你关心的问题、长期的方向，以及你希望如何与世界保持联系。
-    heading: 这个网站为什么存在
+    subtitle: 欢迎来到我的个人网站。
+    heading: 关于我与这里
     paragraphs:
-      - 我需要一个不被信息流推着走的地方。长文可以慢慢展开，随想可以轻轻放下；同一个主题也可以沿着清晰的顺序持续生长。
-      - 所有文章都从本地 Markdown 文件开始。这意味着我可以继续在 Typora 里写作，也意味着内容不会被某个编辑器或平台锁住。
-    quote: 写作不是把已经想明白的东西记下来，而是在句子之间发现自己还没有想明白什么。
+      - 一名工程师 / 创作者。平时主要关注系统开发、技术探索与软件设计。
+      - 这里是我的公开工作台与数字自留地。比起社交网络上的碎片动态，我更倾向于把探索过程沉淀为有据可查的代码、设计与长篇笔记。
+    quote: ""
     focus:
-      - 将自己的关注方向写在这里
-      - 用文章积累可迁移的知识
-      - 为长期写作留出稳定的空间
+      - 软件工程与系统架构
+      - 原生工具与高质量交互
+      - 个人长期知识沉淀
     cta:
       href: /blog
-      label: 从博文开始
+      label: 浏览博文
   garden:
     title: 一个基于 Markdown 的个人博客框架。
     subtitle: ""
 
-footer: 保持独立，持续写作。
+footer: 持续记录与构建。