前言

你用 Obsidian 写了上百篇笔记，有些内容想分享出去。但一看传统博客方案——Hugo 要装 Go 环境、Hexo 要跑命令行、Notion 导出格式又乱七八糟——瞬间没了动力。

有没有一种方式，在 Obsidian 里写完笔记，点一下就发布到互联网上，不需要碰任何代码和命令行？

Digital Garden 就是这个方案。它是 Obsidian 的一个社区插件，让你的笔记直接变成一个带搜索、目录、关系图谱的静态博客站点。整个过程只需要点击，不需要写一行代码。

方案概览

什么是 Digital Garden

先说人话：Digital Garden 是一个 Obsidian 插件，把你的笔记推送到 GitHub，再由 Vercel 自动构建成网站。

你在 Obsidian 里给笔记加一个 dg-publish: true 的属性，执行发布命令，插件就会把笔记推到 GitHub 仓库。Vercel 检测到仓库变化后自动重新构建，几秒钟后网站就更新了。

技术架构

graph LR
    A[Obsidian] -->|插件推送笔记| B[GitHub 仓库]
    B -->|自动触发构建| C[Vercel]
    C -->|部署| D[你的博客站点]
    A -->|Apply Settings| B

整个链路：Obsidian 负责写作和发布，GitHub 做版本管理和存储，Vercel 做构建和托管。三者通过自动化串联，你只需要在 Obsidian 里操作。

与传统方案对比

Digital Garden 最大的优势是：写作和发布在同一个工具里完成，且原生支持 Obsidian 的双链、图谱等特性。

前置准备

开始之前，你需要准备三样东西：

• GitHub 账号：用来存放博客的源码仓库
• Vercel 账号：用 GitHub 账号直接登录即可，地址 https://vercel.com
• Obsidian：安装 Digital Garden 社区插件

安装插件的方法：Obsidian → 设置 → 第三方插件 → 浏览 → 搜索 "Digital Garden" → 安装 → 启用。

部署模板

这一步使用官方提供的一键部署，不要手动 fork 仓库再导入 Vercel（后面踩坑记录会解释为什么）。

操作步骤

1. 打开 Digital Garden 官方模板仓库：https://github.com/oleeskild/digitalgarden

2. 点击 README 中的 "Deploy with Vercel" 按钮，或者直接访问：

https://vercel.com/new/clone?repository-url=https://github.com/oleeskild/digitalgarden

3. Vercel 会引导你创建一个新的 GitHub 仓库（从模板 clone），给仓库起个名字，比如 digitalgarden

4. 点击 Deploy，等待构建完成（大约 1 分钟）

5. 部署成功后，你会看到一个默认页面，提示你还没有发布任何笔记。这是正常的。

记下 Vercel 分配的域名（类似 digitalgarden-xxx.vercel.app），后面要用。

配置 Obsidian 插件

生成 GitHub Token

1. 访问 https://github.com/settings/tokens/new?scopes=repo

2. 填写信息：

   • Note：digitalgarden（随意填写）
   • Expiration：建议选 No expiration
   • 确认 repo 权限已勾选

3. 点击 Generate token

4. 复制 token（只显示一次，务必保存好）

填写插件配置

打开 Obsidian → 设置 → Digital Garden，填写三个字段：

• GitHub repo name：你在 Vercel 部署时创建的仓库名，比如 digitalgarden
• GitHub Username：你的 GitHub 用户名
• GitHub token：刚才生成的 token

配置 Note Settings

在插件设置中找到 Note Settings，建议开启以下功能：

配置 Appearance Settings

在 Appearance Settings 中可以选择主题。插件支持所有 Obsidian 社区主题，选择喜欢的主题后选择 dark 或 light 模式。

关闭 Slugify（中文用户必做）

在插件设置中找到 Slugify Note URL，关掉它。

默认的 slugify 会把中文字符全部去掉，导致文章 URL 变成空的或者只剩英文部分。关闭后，中文文件名会完整保留在 URL 中。

应用设置

以上配置完成后，点击 "Apply settings to site" 按钮。插件会把所有设置推送到 GitHub 仓库，Vercel 检测到变化后会自动重新构建。

发布笔记

创建首页

创建一个笔记作为博客首页（比如 Home.md），添加两个属性：

---
dg-publish: true
dg-home: true
---

• dg-publish: true：标记为可发布
• dg-home: true：标记为首页

在内容中可以用 Wikilink 链接到其他文章：

# Welcome to My Digital Garden

## Articles

- [[基于Kind搭建测试集群]]

发布文章

给想发布的笔记添加属性：

---
dg-publish: true
---

然后按 Cmd+P（Mac）或 Ctrl+P（Windows），搜索并执行 "Digital Garden: Publish Single Note"。

插件会将笔记推送到 GitHub，Vercel 自动重新构建，通常几十秒后就能在网站上看到更新。

批量管理

按 Cmd+P，搜索 "Digital Garden: Publication Center"，可以看到：

• 哪些笔记已发布
• 哪些笔记有本地修改未同步
• 批量发布或删除笔记

Wikilink 写法

Digital Garden 支持 Obsidian 的 Wikilink 语法。在已发布的笔记中，[[笔记名]] 会自动渲染为可点击的内部链接。

如果链接目标笔记没有设置 dg-publish: true，访客点击后会看到"页面不存在"的提示。

自定义域名

默认的 Vercel 域名比较长，你可以绑定自己的域名。

Vercel 端配置

1. 进入 Vercel → 你的项目 → Settings → Domains
2. 在输入框中输入你的域名，比如 blog.example.com
3. 点击 Add

DNS 端配置

去你的域名 DNS 服务商，添加一条 CNAME 记录：

如果是根域名（example.com），添加 A 记录：

等待生效

DNS 记录生效后（通常几分钟），Vercel 会自动签发 HTTPS 证书。之后就可以通过你的自定义域名访问博客了。

踩坑记录

以下是实际部署过程中踩过的坑，记录下来供参考。

坑1：手动导入 Vercel 导致环境变量覆盖

现象：插件设置里开启了 filetree、search、TOC 等功能，Apply settings 也点了，但网站上这些功能全部不显示。

原因：如果不使用官方的"Deploy with Vercel"按钮，而是手动 fork 仓库后在 Vercel 中导入，Vercel 会检测到仓库中的 .env 文件，弹出环境变量配置界面。如果直接跳过不填值，Vercel 会创建一批空值的环境变量。

Digital Garden 的构建代码使用 dotenv 库从 .env 文件读取配置。但 dotenv 的默认行为是不覆盖已存在的环境变量。Vercel 的空环境变量优先级高于 .env 文件，导致所有功能开关都读取到空字符串（等同于 false）。

解决方案：

• 预防：使用官方的"Deploy with Vercel"按钮部署，它不会创建任何环境变量
• 修复：如果已经踩坑，去 Vercel → Settings → Environment Variables，删除所有环境变量，然后 Redeploy

坑2：中文文件名被 Slugify 吃掉

现象：中文笔记发布后，URL 中只剩英文部分，中文字符全部消失。比如 基于Kind搭建测试集群 变成了 /kind/。

原因：Digital Garden 默认开启 URL slugify，会把非 ASCII 字符全部去掉。

解决方案：在插件设置中找到 Slugify Note URL，关掉它。关闭后中文文件名会完整保留在 URL 中。

坑3：不要手动改仓库文件

现象：手动修改仓库中的 .env、custom-style.scss 等文件后，下次在 Obsidian 插件中点"Apply settings to site"或发布笔记时，手动修改的内容被覆盖。

原因：插件的"Apply settings to site"会将 Obsidian 中的配置状态完整推送到仓库的 .env 文件。插件是这些配置文件的唯一管理者。

解决方案：所有配置类操作都通过 Obsidian 插件界面完成，不要直接修改仓库中的配置文件。自定义 CSS 可以写在 src/site/styles/custom-style.scss 中，这个文件插件不会覆盖。

参考资料