说明目录
Garden 使用说明总览

一个基于 Markdown 的个人博客框架。

用 Markdown 写文章、随想和专栏，保存在自己的 Git 仓库里。

Garden 是一个 Claude 风格的博客框架，文章用 Markdown 写，组件用自然语言描述就行。

一个完整的例子

下面四步是同一篇稿子的真实过程，命令输出均来自实际运行结果。

1. 作者写一句想法

在需要组件的地方写一个 garden compose 围栏，里面写清想让读者做什么、看到什么：

## 写作节奏

```garden compose
让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
```

2. Agent 扫描并写回组件

对 Agent 说「编译这篇：content/posts/writing-pace.md」。Agent 按站点里的 garden-compose skill 先运行 npx garden ui scan，拿到这一块的行号、原话和哈希：

$ npx garden ui scan content/posts/writing-pace.md
{
  "file": "content/posts/writing-pace.md",
  "draft": false,
  "blocks": [
    {
      "lang": "garden-compose",
      "status": "uncompiled",
      "startLine": 9,
      "intentHash": "cb3a3569",
      "intent": "让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。",
      "section": "写作节奏"
    }
  ]
}

接着 Agent 读取 npx garden ui prompt 里的组件目录，写出 garden compose，再用 npx garden ui apply 按 --intent-hash 只替换这一块，围栏外的正文逐字节不变：

$ npx garden ui apply content/posts/writing-pace.md --intent-hash cb3a3569 --file new.md
{"ok":true,"file":"content/posts/writing-pace.md","kind":"garden","line":9}

3. 提交前钩子检查并调用修复技能

首次运行 garden sync 或 garden dev 时，Garden 会在 .git/hooks/pre-commit 写入 exec npx --no-install garden ui check --staged --quiet。如果作者在第 2 步之前直接提交，钩子会拦下提交，并显示诊断和调用项目技能的短指令：

$ git commit -m "写作节奏"
content/posts/writing-pace.md:9  -  compose-uncompiled  还有没编译的 compose 想法
请调用 garden-compose skill（.agents/skills/garden-compose/SKILL.md），修复以上错误块后重新校验。

终端只显示诊断和一条指向项目 garden-compose skill 的短指令；默认不写文件、不复制剪贴板、不输出原文或组件目录。修复后钩子静默返回 0。

4. 页面渲染结果

第 2 步写回的 garden compose 块在文章页面直接渲染为可拖动的交互控件：

写完 8000 字需要6 周不足一周按一周算
每天多写几百字，比每周多写一天更快。

人和 Agent 用同一套工具

Agent 找块用的 npx garden ui scan、写回用的 npx garden ui apply、自查用的 npx garden ui check，和作者提交时 pre-commit 钩子运行的检查是同一组命令。钩子拦截时给出的技能调用短指令，就是发给 Agent 的下一步。详见 用 AI 写作。

下面几节介绍不用 Agent 也会自动生效的版面与组件规则。

标题分行与 740px 正文列

标题里写一个「丨」，就在那里分成两行，字号按较长一行自动计算。正文保持在 740px 阅读列内，宽图会在两侧留白里对称外扩，不会盖住导航和目录。

下面这张透明底的线稿在深色模式下会自动垫上暖白底，不用另做一套配图：

740px 正文阅读列、1040px 宽图区与 1340px 宽表区示意（透明背景黑线 SVG，深色模式下自动衬上 #faf9f5 暖白纸底）。

多列宽表格自动向外延伸

表格不折行时比正文列宽，就会向两侧对称拓宽，文章页最宽 1340px。下面这张宽表在桌面端会伸出正文列：

内容形态源文件位置页面如何处理长文与媒体细节适用场景
长篇技术文章content/posts/<slug>.md 及同名资源目录自动测量本地配图宽高写入 HTML 防抖动，支持 丨 标题分行、宽图宽表外扩、LaTeX 公式与 Mermaid 图表系统设计拆解、源码走读、排障复盘与长篇读书笔记
随想与日常记录content/thoughts/<slug>.md支持多图宫格、原生音视频播放（image / audio / video）以及外部网页链接卡片（link）几句话的灵感、终端截图、短音视频与日常链接摘录
主题系列专栏content/columns.yaml按顺序串联 content/posts/ 下的多篇长文，在阅读页自动生成专栏进度与上下篇导航连载教程、专题研究或按章节组织的系统笔记

代码块与「对比上一版」切换

在改好的完整代码下面写一句想法说明和上一版比改了什么，Agent 会生成一段紧挨着的 diff 代码块；你也可以直接手写 diff。完整代码和 diff 紧挨着时，页面会把它们合成一个可切换「代码」和「对比上一版」的代码框，复制按钮始终复制新版完整代码。

pages:
  garden:
    title: "用 Markdown 写丨推送之后网站自己更新"
    subtitle: "用 Markdown 写文章、随想和专栏，保存在自己的 Git 仓库里。"

提醒

diff 代码块前面必须紧挨着一段完整代码块；如果单独放一段 diff 而前面没有完整代码，npx garden check 会报 diff-orphan 错误。

提示框支持自定标题

在 > [!TIP] 同一行后面直接写文字（或者下一行单独放一行粗体），会替换默认的「建议」标题。支持 NOTE、TIP、IMPORTANT、WARNING、CAUTION 等常见类型。

在文章里嵌入结构化组件

需要数字、对比、时间线或图表时，在 garden compose 内组合对应组件。下面是一组数值：

正文阅读列
740px
段落、代码块与列表的默认列宽
宽幅配图区
1040px
截图按像素宽度的一半显示，像素宽度约 2000px 以上时展开到这个宽度
多列宽表区
1340px
宽表格在桌面端向两侧对称外扩上限

组件页以 garden compose 为唯一 Garden 作者入口，另含链接卡片、来源胶囊和本地图片。内容、布局和交互在 compose 内组合。效果见左侧导航的 组件总览。

从初始化到日常写作

站点仓库只放配置、文章和静态资源，渲染和构建由 hd-garden 包完成。本地建站并预览：

npx hd-garden init my-blog
cd my-blog
npm install
make dev

写完运行 make update，检查通过后会提交并推送。细节见各章：

目录