hd-garden 0.6.0 → 0.7.0

package/docs/handbook/components/figure.md

@@ -0,0 +1,70 @@
+---
+title: 分区结构图（figure）
+navTitle: 分区结构图
+description: 为 SVG 结构图加上分区高亮按钮，点击切换对应区域与文字说明。
+section: components
+order: 36
+badge: figure
+---
+
+```garden figure
+caption: 点击上方按钮切换高亮各步骤
+svg: |
+  <svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
+    <rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. garden sync</text>
+    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">解析 Markdown 与图片尺寸</text>
+    <path d="M214 55 H236" stroke="var(--muted)" stroke-width="1.5"/>
+    <rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <text data-p="build" x="340" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">2. garden build</text>
+    <text data-p="build" x="340" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">生成静态页面与搜索索引</text>
+    <path d="M444 55 H466" stroke="var(--muted)" stroke-width="1.5"/>
+    <rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <text data-p="validate" x="570" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">3. pages:validate</text>
+    <text data-p="validate" x="570" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">检查 index.html 与禁用文件</text>
+  </svg>
+parts:
+  - id: sync
+    label: 1. 同步内容
+    text: 扫描 `content/` 与 `docs/handbook/`，复制随文附件并生成 `.garden/generated-content.ts`。
+  - id: build
+    label: 2. 构建页面
+    text: 根据 `STATIC_EXPORT=1` 预渲染所有页面路由，输出 RSS、sitemap 与全文搜索文件。
+  - id: validate
+    label: 3. 导出校验
+    text: 运行 pages:validate，确认导出目录里有 `index.html`，且没有 `.env`、源码目录、`.map` 或 `.md` 文件和软链接。
+```
+
+````markdown
+```garden figure
+caption: 点击上方按钮切换高亮各步骤
+svg: |
+  <svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
+    <rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. garden sync</text>
+    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">解析 Markdown 与图片尺寸</text>
+    <rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+  </svg>
+parts:
+  - id: sync
+    label: 1. 同步内容
+    text: 扫描 `content/` 与 `docs/handbook/`，复制随文附件并生成 `.garden/generated-content.ts`。
+  - id: build
+    label: 2. 构建页面
+    text: 根据 `STATIC_EXPORT=1` 预渲染所有页面路由，输出 RSS、sitemap 与全文搜索文件。
+  - id: validate
+    label: 3. 导出校验
+    text: 运行 pages:validate，确认导出目录里有 `index.html`，且没有 `.env`、源码目录、`.map` 或 `.md` 文件和软链接。
+```
+````
+
+- **用**：展示模块架构或数据流向，需要读者点击按钮逐块查看对应区域职责时（SVG 内优先使用 `var(--well)`、`var(--ink)`、`var(--muted)` 等主题变量以兼容深色模式）。
+- **别用**：不需要分区点击说明的普通流程图或截图，直接用标准 Markdown 图片或 `mermaid` 代码块。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `svg` | 与 `image` 二选一 | 多行字符串 | 内联 `<svg>` 源码；在需要高亮的分组上标注 `data-p="<id>"` |
+| `image` | 与 `svg` 二选一 | 路径字符串 | 普通图片路径（可写成 `{ src, alt }`） |
+| `parts` | 否 | `{ id, label, text }[]` | 顶部分区切换按钮及底部对应的说明文字 |
+| `caption` | 否 | 字符串 | 图框下方的图注说明 |

package/docs/handbook/components/file/checklist.md

@@ -0,0 +1,17 @@
+# 站点发布前检查清单
+
+在运行 `make update` 推送更新前，可以核对以下几项：
+
+## 1. 文章 Front Matter 与路径
+
+- [x] `title`、`date`、`description` 均已填写，文件名只用小写字母、数字和连字符
+- [x] 本地图片与随文附件放在文章同名目录下，使用 `./<slug>/file.ext` 相对路径引用
+- [x] 正式发布的文章已去掉 `draft: true`
+
+## 2. 本地校验命令
+
+| 命令 | 检查内容 |
+| :--- | :--- |
+| `npx garden check content/posts/<slug>.md` | 检查单篇文章的组件字段、代码对比与图片附件路径 |
+| `make check` | 运行 `npx garden sync && npx garden build` 校验全站构建 |
+| `CONTENT_INCLUDE_DRAFTS=1 make dev` | 在本地连同草稿和定时文章一起预览 |

package/docs/handbook/components/file.md

@@ -0,0 +1,32 @@
+---
+title: 文件下载与预览（file）
+navTitle: 文件下载与预览
+description: 提供单个或一组附件下载，自动显示格式与大小，支持在页内展开预览。
+section: components
+order: 39
+badge: file
+---
+
+```garden file
+src: ./file/checklist.md
+title: 发布前检查清单
+note: Markdown 附件示例，可点击「预览」在当前页展开阅读，或直接下载原文件
+```
+
+````markdown
+```garden file
+src: ./file/checklist.md
+title: 发布前检查清单
+note: Markdown 附件示例，可点击「预览」在当前页展开阅读，或直接下载原文件
+```
+````
+
+- **用**：随文章提供配置文件、数据表、PDF、图片或 Markdown 附件供读者下载与页内预览时（多文件可用 `files` 数组）。
+- **别用**：正文里本来就要直接展示的配图用标准 Markdown 图片语法 `![]()`，不要放进 `file` 组件。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `src` | 单文件必填 | 路径或完整链接 | 相对当前 Markdown 文件的本地路径（不得越出 `content/`）、`/public` 路径或 `https://` 链接 |
+| `title` | 否 | 字符串 | 显示的文件标题（默认取文件名；多文件模式下作为分组标题） |
+| `note` | 否 | 字符串 | 文件名下方的简短说明 |
+| `files` | 多文件必填 | `{ src, title?, note? }[]` | 一次列出多个文件时使用（与顶层 `src` 二选一） |

package/docs/handbook/components/html.md

@@ -0,0 +1,67 @@
+---
+title: 嵌入网页片段（html）
+navTitle: 嵌入网页片段
+description: 在沙盒 iframe 中运行独立的 HTML、CSS 与 JavaScript 演示片段。
+section: components
+order: 37
+badge: html
+---
+
+```garden html
+title: 字符长度与预计阅读耗时小工具
+height: 156
+code: |
+  <!doctype html>
+  <html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body { margin: 0; padding: 16px 18px; font: 14px/1.6 system-ui, sans-serif; color: #1b1a18; background: #faf9f5; }
+      input { width: 100%; box-sizing: border-box; padding: 8px 10px; border: 1px solid #d5d1c8; border-radius: 6px; font: inherit; background: #fff; color: #1b1a18; }
+      .meta { margin-top: 10px; color: #6e6b64; font-variant-numeric: tabular-nums; }
+      strong { color: #1b1a18; }
+    </style>
+  </head>
+  <body>
+    <input id="txt" value="把文章放在自己的 Git 仓库里，推送后自动构建。" aria-label="输入示例文本" />
+    <div class="meta">当前字符数：<strong id="count">23</strong> 字</div>
+    <script>
+      const input = document.getElementById("txt");
+      const count = document.getElementById("count");
+      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
+    </script>
+  </body>
+  </html>
+```
+
+````markdown
+```garden html
+title: 字符长度与预计阅读耗时小工具
+height: 156
+code: |
+  <!doctype html>
+  <html lang="zh-CN">
+  <head><meta charset="utf-8" /></head>
+  <body>
+    <input id="txt" value="把文章放在自己的 Git 仓库里，推送后自动构建。" />
+    <div>当前字符数：<strong id="count">23</strong> 字</div>
+    <script>
+      const input = document.getElementById("txt");
+      const count = document.getElementById("count");
+      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
+    </script>
+  </body>
+  </html>
+```
+````
+
+- **用**：需要运行自定义 DOM 脚本、Canvas 绘图或独立 HTML 页面片段时（支持 `code` 内联或 `src` 引用文章同名目录下的 `.html` 文件）。
+- **别用**：只需要滑杆调参数算公式时用 [`interactive`](/garden/components/interactive)；静态结构图用 [`figure`](/garden/components/figure)。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `src` | 与 `code` 二选一 | 相对路径字符串 | 引用与当前 Markdown 同目录（或同名子目录）下的 `.html` 文件 |
+| `code` | 与 `src` 二选一 | 多行字符串 | 直接内联编写的 HTML 源码（也可用别名 `html`） |
+| `title` | 建议 | 字符串 | 卡片顶部栏标题及 `iframe` 的无障碍标题 |
+| `height` | 否 | 数字 | 初始高度（像素，默认 `260`；加载后也会随内容高度自动调整） |
+| `caption` | 否 | 字符串 | 底部的图注说明 |

package/docs/handbook/components/interactive.md

@@ -0,0 +1,65 @@
+---
+title: 可调公式与参数（interactive）
+navTitle: 可调公式与参数
+description: 提供滑杆或单选按钮，让读者调整变量并实时计算公式与图表结果。
+section: components
+order: 38
+badge: interactive
+---
+
+```garden interactive #reading-time
+caption: 示例：按字数、阅读速度和配图数估算一篇文章的阅读时间。数字只用来演示组件，不是统计结果。
+---
+<State words={6000} speed={400} images={8} />
+<Let textMinutes={round(words / speed)} />
+<Let imageMinutes={round(images * 12 / 60)} />
+<Let parts={[{ part: "正文", minutes: textMinutes }, { part: "配图", minutes: imageMinutes }]} />
+
+<Slider bind="words" label="正文字数" min={1000} max={20000} step={500} unit="字" />
+<Slider bind="speed" label="阅读速度" min={200} max={800} step={50} unit="字/分钟" />
+<Slider bind="images" label="配图数" min={0} max={30} step={1} unit="张" />
+
+<Stat label="示例：预计阅读时间" value={textMinutes + imageMinutes} unit="分钟" hint="配图按每张 12 秒估算" />
+<Chart data={parts} x={part} yLabel="分钟">
+  <Bar y={minutes} label="示例" />
+</Chart>
+```
+
+````markdown
+```garden interactive #reading-time
+caption: 示例：按字数、阅读速度和配图数估算一篇文章的阅读时间。数字只用来演示组件，不是统计结果。
+---
+<State words={6000} speed={400} images={8} />
+<Let textMinutes={round(words / speed)} />
+<Let imageMinutes={round(images * 12 / 60)} />
+<Let parts={[{ part: "正文", minutes: textMinutes }, { part: "配图", minutes: imageMinutes }]} />
+
+<Slider bind="words" label="正文字数" min={1000} max={20000} step={500} unit="字" />
+<Slider bind="speed" label="阅读速度" min={200} max={800} step={50} unit="字/分钟" />
+<Slider bind="images" label="配图数" min={0} max={30} step={1} unit="张" />
+
+<Stat label="示例：预计阅读时间" value={textMinutes + imageMinutes} unit="分钟" hint="配图按每张 12 秒估算" />
+<Chart data={parts} x={part} yLabel="分钟">
+  <Bar y={minutes} label="示例" />
+</Chart>
+```
+````
+
+- **用**：解释带多个变量的数学关系、容量估算或参数权衡，需要读者拖动滑杆实时观察结果变化时。
+- **别用**：只有 `<Steps>` 而没有任何状态或输入控件，会报 `steps-prose` 错误；所有 `<Let>` 都只是一次乘法（形如 `a * b`），会报 `interactive-trivial` 错误。遇到这两种情况，改用普通段落。
+
+分隔线 `---` 上方是块头，下方是标签。常用的写法：
+
+| 字段或标签 | 必填 | 说明 |
+| :--- | :--- | :--- |
+| `#reading-time` | 建议 | 写在围栏头，块的标识，只能用小写字母、数字和连字符 |
+| `caption` | 是 | 一句话说明这块交互想让读者看到什么 |
+| `intent` | 否 | 这块交互由哪句想法编译而来，写成文字 |
+| `expect` | 否 | 数组，每条写成 `{ given: {...}, 名字: 期望值 }`，检查时会按给定状态算一遍 |
+| `<State />` | 是 | 声明会变的量和默认值，例如 `<State words={6000} />` |
+| `<Let />` | 否 | 由别的量算出来的值，也可以写数据数组 |
+| `<Slider />` / `<Choice />` / `<Toggle />` | 是 | 输入控件，用 `bind` 绑定一个状态；`Slider` 必填 `label`、`min`、`max` |
+| `<Stat />` | 否 | 显示一个醒目的数字，必填 `label` 与 `value` |
+| `<Chart />` | 否 | 用 `sweep` 画函数曲线，或用 `data` 加 `<Bar>` / `<Line>` 画数据 |
+
+全部标签和属性见 `npx garden ui catalog` 生成的组件目录。

package/docs/handbook/components/stat.md

@@ -0,0 +1,55 @@
+---
+title: 数字指标（stat）
+navTitle: 数字指标
+description: 将 2～4 组关键数字、单位与简短说明并排展示。
+section: components
+order: 32
+badge: stat
+---
+
+```garden stat
+items:
+  - label: 正文列宽
+    value: "740"
+    unit: px
+    caption: 默认阅读列宽度
+  - label: 宽图上限
+    value: "1040"
+    unit: px
+    caption: 左右各最多向外延伸 150px
+  - label: 宽表上限
+    value: "1340"
+    unit: px
+    caption: 左右各最多向外延伸 300px
+```
+
+````markdown
+```garden stat
+items:
+  - label: 正文列宽
+    value: "740"
+    unit: px
+    caption: 默认阅读列宽度
+  - label: 宽图上限
+    value: "1040"
+    unit: px
+    caption: 左右各最多向外延伸 150px
+  - label: 宽表上限
+    value: "1340"
+    unit: px
+    caption: 左右各最多向外延伸 300px
+```
+````
+
+- **用**：把分散在段落里的 2～4 个核心数字、阈值或规格并排摆出来时。
+- **别用**：只有一个数字时直接写在正文句子里；有多行多列维度时改用 Markdown 表格。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `items` | 否 | 对象数组 | 展示多项指标时使用；单卡可直接把字段写在顶层 |
+| `label` | 是 | 字符串 | 指标名称（显示在数字上方） |
+| `value` | 是 | 字符串或数字 | 核心数值（等宽大字号显示） |
+| `unit` | 否 | 字符串 | 紧跟在数值右侧的单位 |
+| `caption` | 否 | 字符串 | 数值下方的简短说明 |
+| `text` | 否 | 字符串 | 补充说明文字 |
+| `source` | 否 | 字符串或 `{ title, url }` | 数据出处角标 |

package/docs/handbook/components/timeline.md

@@ -0,0 +1,50 @@
+---
+title: 时间线（timeline）
+navTitle: 时间线
+description: 按时间或步骤顺序排列版本演进、排查过程与关键节点。
+section: components
+order: 34
+badge: timeline
+---
+
+```garden timeline
+title: 静态发布流水线执行步骤
+items:
+  - date: 步骤 1
+    title: 同步内容与静态资源
+    text: 运行 `npx garden sync`，校验 Front Matter、复制图片附件并生成搜索索引与 RSS。
+  - date: 步骤 2
+    title: 构建静态站点产物
+    text: 运行 `STATIC_EXPORT=1 npx garden build`，把全部路由预渲染到 `dist/client/`。
+  - date: 步骤 3
+    title: 校验静态页面并部署
+    text: 运行 `npm run pages:validate` 确认有 `index.html`，且没有混入 `.env`、源码目录、`.map` 或 `.md` 文件和软链接，通过后发布到 GitHub Pages。
+```
+
+````markdown
+```garden timeline
+title: 静态发布流水线执行步骤
+items:
+  - date: 步骤 1
+    title: 同步内容与静态资源
+    text: 运行 `npx garden sync`，校验 Front Matter、复制图片附件并生成搜索索引与 RSS。
+  - date: 步骤 2
+    title: 构建静态站点产物
+    text: 运行 `STATIC_EXPORT=1 npx garden build`，把全部路由预渲染到 `dist/client/`。
+  - date: 步骤 3
+    title: 校验静态页面并部署
+    text: 运行 `npm run pages:validate` 确认有 `index.html`，且没有混入 `.env`、源码目录、`.map` 或 `.md` 文件和软链接，通过后发布到 GitHub Pages。
+```
+````
+
+- **用**：按先后顺序记录故障排查时间点、演进阶段或构建流水线步骤（至少 2 个节点）时。
+- **别用**：没有时间或先后顺序的并列要点，直接用无序列表。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `title` | 否 | 字符串 | 时间线顶部的总标题 |
+| `items` | 是 | 对象数组（至少 2 项） | 按顺序排列的节点列表 |
+| `items[].date` | 否 | 字符串 | 时间、阶段或步骤编号（显示在节点标题上方） |
+| `items[].title` | 是 | 字符串 | 节点标题 |
+| `items[].text` | 否 | 字符串 | 节点详细说明 |
+| `items[].source` | 否 | 字符串或 `{ title, url }` | 节点出处角标 |

package/docs/handbook/components.md

@@ -0,0 +1,30 @@
+---
+title: 组件总览
+navTitle: 组件总览
+description: 9 个内置 garden 组件的用途、围栏名称与使用约束。
+section: components
+order: 30
+---
+
+当标准 Markdown 段落、列表或表格不够表达时，可以在文章里使用 ```` ```garden <name> ```` 代码块插入内置组件。所有组件名均使用英文，内部使用 YAML（`interactive` 在 `---` 下方使用声明式标签）编写参数。
+
+## 9 个组件速查表
+
+| 组件名 | 代码块围栏 | 适用场景 | 必填字段或下限 |
+| :--- | :--- | :--- | :--- |
+| [知识卡片](/garden/components/card) | ```` ```garden card ```` | 介绍论文、开源项目或模块要点 | 至少填 `description` 或 `points` |
+| [数字指标](/garden/components/stat) | ```` ```garden stat ```` | 并排展示 2～4 组关键数值与单位 | 每项必填 `label` 与 `value` |
+| [并排对比](/garden/components/compare) | ```` ```garden compare ```` | 左右并列对比 2～3 种方案或改动前后差异 | `items` 至少 2 项，每格不超过约 60 字 |
+| [时间线](/garden/components/timeline) | ```` ```garden timeline ```` | 按先后顺序串联排查记录或演进阶段 | `items` 至少 2 项 |
+| [条形图表](/garden/components/chart) | ```` ```garden chart ```` | 用数据绘制比例条形图（自带可展开数据表） | `data` 至少 2 行 |
+| [分区结构图](/garden/components/figure) | ```` ```garden figure ```` | 带分区按钮高亮与说明的 SVG / 图片结构图 | `svg` 或 `image` 二选一 |
+| [嵌入网页片段](/garden/components/html) | ```` ```garden html ```` | 在沙盒 `iframe` 中运行独立 HTML/JS 演示 | `src` 或 `code` 二选一 |
+| [可调公式与参数](/garden/components/interactive) | ```` ```garden interactive ```` | 提供滑杆或单选控件实时计算非平凡公式 | 含输入控件且公式不能是单次乘法 |
+| [文件下载与预览](/garden/components/file) | ```` ```garden file ```` | 提供本地或远程文件下载与页内预览 | `src` 或 `files` 二选一 |
+
+## 编写与检查规则
+
+1. **优先使用标准 Markdown**：普通文字说明、有序列表和常规对比表格直接用 Markdown 编写，只有结构化组件能明显提升可读性时才用 `garden` 围栏。
+2. **不要重复展示同一组数据**：`chart` 组件下方自带「查看数据表」折叠区，同一小节内不需要再重复手写一张相同数据的 Markdown 表格。
+3. **支持行内格式**：各组件的 `text`、`description`、`caption`、`points` 等文本字段均支持行内 `**加粗**`、`` `行内代码` `` 和 `<u>荧光笔下划线</u>`。
+4. **本地预览全部组件样式**：运行 `npx garden ui catalog` 会在 `.garden/ui-catalog.html` 生成组件画廊页面，可在浏览器中直接打开查看。

package/docs/handbook/config.md

@@ -0,0 +1,125 @@
+---
+title: 站点与专栏配置
+navTitle: 站点与专栏配置
+description: 配置 site.config.yaml 中的站点信息、各页标题、自定义品牌图标与 content/columns.yaml 专栏。
+section: getting-started
+order: 2
+---
+
+站点的全局文字与外观信息集中在根目录的 `site.config.yaml`，专栏目录集中在 `content/columns.yaml`。修改后运行 `npx garden sync`（或直接 `make dev`）即可生效。
+
+## 1. `site.config.yaml` 完整结构
+
+下面是站点模板默认的 `site.config.yaml` 字段：
+
+```yaml
+name: Garden
+tagline: 写作 · 记录 · 保持好奇
+description: 文章、随想和专栏。
+locale: zh_CN
+# 站点的公开地址。文章里指向这个地址的完整网址会按站内链接显示。
+# url: https://blog.example.com
+# 站点图标，不写时使用 Garden 自带的图标。
+# brand:
+#   logo: brand/logo.svg
+#   favicon: /favicon.svg
+#   appleTouchIcon: /apple-touch-icon.png
+
+author:
+  name: Your Name
+  github: your-github-id
+  githubBio: 一句自我介绍。
+  githubPinned: []
+
+pages:
+  home:
+    title: |-
+      记一些正在做的事，
+      和想清楚的问题。
+    subtitle: 软件、笔记，和偶尔的工作记录。
+  blog:
+    title: 博文
+    subtitle: 写完的长文。
+  thoughts:
+    title: 随想
+    subtitle: 短笔记、图片和链接。
+  columns:
+    title: 专栏
+    subtitle: 按顺序读的一组文章。
+  about:
+    title: 你好，我是 Your Name。
+    subtitle: 文章和笔记都在这里。
+    heading: 关于
+    paragraphs:
+      - 一名工程师。平时写代码，也把想清楚的问题记下来。
+      - 这里放文章、随想和专栏。
+    quote: ""
+    focus:
+      - 软件
+      - 笔记
+      - 日常
+    cta:
+      href: /blog
+      label: 浏览博文
+  garden:
+    title: "用 Markdown 写。\n推送之后，网站自己更新。"
+    subtitle: ""
+
+footer: 持续记录。
+```
+
+### 顶层与作者字段
+
+| 字段 | 说明 |
+| :--- | :--- |
+| `name` | 站点名称，显示在左上角导航栏、浏览器标题后缀与 RSS 订阅源标题 |
+| `tagline` | 站点副标题 |
+| `description` | 站点简介，用于首页 SEO 描述与 RSS 频道描述 |
+| `locale` | 语言与地区标识，默认写 `zh_CN`（下划线格式） |
+| `url` | 站点的公开完整网址（如 `https://blog.example.com`）。配置后，文章里指向该地址的完整链接会自动按站内链接处理 |
+| `author.name` | 作者署名，显示在文章元信息栏、关于页和页脚 |
+| `author.github` | GitHub 用户名（不要写完整网址），用于拼接 GitHub 主页链接及拉取关于页的公开动态 |
+| `author.githubBio` | 当构建环境没有配置 `GITHUB_TOKEN` 时的个人简介降级文字 |
+| `author.githubPinned` | 本地无 `GITHUB_TOKEN` 时的置顶仓库降级列表 |
+| `footer` | 页脚签名文字 |
+
+> [!NOTE]
+> URL 末尾是否带斜杠（Trailing Slash）不由 `site.config.yaml` 控制：静态导出（`STATIC_EXPORT=1`）时始终开启，服务端构建可通过环境变量 `TRAILING_SLASH=1` 开启。
+
+### `pages` 一级页面文案
+
+`pages` 下的每个键对应一个一级路由的页头文字：
+
+- **`pages.home`、`pages.blog`、`pages.thoughts`、`pages.columns`、`pages.garden`**：均使用 `title` 和 `subtitle` 两个字段。其中 `/garden/` 页面会读取 `pages.garden.title`（支持用 `丨` 分成两行）和 `pages.garden.subtitle`。
+- **`pages.about`**：除 `title` 和 `subtitle` 外，还支持 `heading`（正文小标题）、`paragraphs`（段落数组）、`quote`（引言）、`focus`（关注方向标签数组）以及 `cta`（`{ href, label }` 按钮）。
+
+### `brand` 自定义图标与路由重定向
+
+- **`brand.logo`**：左上角站点名左侧的 SVG 标志。文件相对于站点根目录解析（例如放在 `brand/logo.svg`），构建时会内联进页头并跟随当前文字颜色。设为 `false` 可隐藏左上角图标。
+- **`brand.favicon` 与 `brand.appleTouchIcon`**：放在 `public/` 目录下的图标路径（如 `/favicon.svg`、`/apple-touch-icon.png`）；`appleTouchIcon` 设为 `false` 可不输出。
+- **`redirects`**：旧文章改路径后，可在 `site.config.yaml` 顶层配置 `redirects` 映射（例如 `"/2024/01/20/old-post/": "/blog/new-post/"`），构建时会在旧路径生成跳转页，正文里的站内旧链接也会自动指向新地址。
+
+## 2. 配置主题专栏（`content/columns.yaml`）
+
+专栏用于把 `content/posts/` 里的多篇长文按阅读顺序编成一组。编辑 `content/columns.yaml`：
+
+```yaml
+columns:
+  - slug: building-in-public
+    title: 一个人造产品
+    status: 连载中
+    description: 从最小闭环到验证发布的完整记录。
+    cover: windowsill-herbs.svg
+    posts:
+      - building-in-public/smallest-closed-loop
+      - building-in-public/ship-with-evidence
+```
+
+| 字段 | 必填 | 说明 |
+| :--- | :--- | :--- |
+| `slug` | 是 | 专栏标识，只能包含小写字母、数字和连字符，生成路由 `/columns/<slug>/<post>` |
+| `title` | 是 | 专栏名称（同时会显示在 `/blog` 文章列表对应文章的右侧） |
+| `description` | 是 | 专栏简介，显示在 `/columns` 列表卡片上 |
+| `status` | 否 | 状态文字（如 `连载中` 或 `已完结`） |
+| `cover` | 否 | 专栏封面图路径（相对 `content/covers/`） |
+| `posts` | 是 | 按阅读顺序排列的文章路径列表（相对于 `content/posts/`，不带 `.md` 后缀） |