Obsidian-Digital-Garden插件详细指南

Obsidian Digital Garden 插件 Web 发布完全指南

#resource / obsidian #tech / ops / deploy #type / howto #status / evergreen

[!info] related notes

Obsidian同步与部署指南

Obsidian-Git插件详细指南

Quartz-4.0静态部署指南

Obsidian知识库静态部署

Obsidian学习追踪系统

Obsidian Digital Garden 插件详细指南

核心功能：一键发布 Obsidian 笔记到个人网站、链接预览、实时更新
难度级别：⭐⭐⭐
推荐指数：⭐⭐⭐⭐⭐
必装程度：分享笔记者必用

什么是 Digital Garden

定义： Obsidian Digital Garden 是一个插件，可以一键将你的 Obsidian 笔记发布到个人网站上，支持链接预览、实时更新、自定义主题。

核心特点：

✅ 零代码部署 - 无需编程基础
✅ 实时发布 - 修改笔记立即更新网站
✅ 链接预览 - 悬浮预览笔记内容
✅ 高度自定义 - 修改样式与配置
✅ SEO 友好 - 自动生成元数据
✅ 免费托管 - GitHub Pages + Vercel

与其他方案对比

部署方案对比表

方案	复杂度	学习成本	发布速度	自定义	部署成本	推荐度
Digital Garden	⭐	⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	免费	⭐⭐⭐⭐⭐
Quartz 4.0	⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	免费	⭐⭐⭐⭐
Obsidian Publish	⭐	⭐	⭐⭐⭐⭐⭐	⭐	$96/年	⭐⭐⭐
Obsidian Git + Hugo	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	免费	⭐⭐

选择建议：

需要快速发布？           → Digital Garden ✅
需要高度定制？           → Quartz 4.0 ✅
需要官方支持？           → Obsidian Publish ✅
有编程基础，要完全控制？ → Quartz 4.0 + 自定义 ✅

功能概览

📌 插件功能清单

功能	说明	使用场景
一键发布	单个笔记/整个库一键发布	快速分享想法、发布文章
实时更新	修改笔记，网站立即更新	博客、知识库、日记
链接预览	悬浮预览内部链接内容	知识关联浏览
反向链接	显示哪些笔记链接到当前页	知识图谱、网络效应
搜索功能	网站内搜索	快速找到需要的内容
暗黑模式	自动切换 Light/Dark	用户友好体验
评论系统	社交互动（可选）	接收读者反馈
分析统计	流量统计（可选）	了解内容受欢迎度

🎨 样式支持

代码高亮与语言标记
数学公式（LaTeX/KaTeX）
Markdown 扩展语法（表格、脚注、上下标）
自定义 CSS
响应式设计（自动适配移动设备）

环境准备

前置条件

✅ 有 GitHub 账户
✅ Obsidian 已安装
✅ 一个 Obsidian 库（包含要发布的笔记）

创建 GitHub 仓库

步骤 1：创建新仓库

访问 https://github.com/new
仓库名称：digital-garden（或任意名称）
可见性：Public（必须公开）
点击”Create repository”

步骤 2：获取仓库 URL

例如：https://github.com/YOUR_USERNAME/digital-garden

配置 GitHub Pages

进入仓库 → Settings
在左侧菜单找到 Pages
Build and deployment
- Source: GitHub Actions
- 如果没有 Actions，往下看会有选项
检查仓库是否已有 workflow 文件
- 如果没有，稍后插件会自动创建

插件安装与配置

安装插件

在 Obsidian 中：

Settings → Community plugins → Browse
搜索 “Digital Garden”
点击 Install
点击 Enable

或手动安装：

# 克隆插件到 Obsidian 插件目录
cd ~/.obsidian/plugins  # Mac/Linux
# 或 C:\Users\YourName\AppData\Roaming\obsidian\plugins  # Windows

git clone https://github.com/oleeskild/obsidian-digital-garden.git digital-garden
cd digital-garden
npm install
npm run dev

配置插件

打开插件设置： Settings → Community plugins → Digital Garden → Options

核心设置

设置项	说明	示例值
GitHub Username	GitHub 用户名	your-username
GitHub Repository	仓库名	digital-garden
GitHub Token	GitHub 个人令牌	ghp_xxxxx…（见下）
Base URL	网站 URL（可选）	https://yourdomain.com

获取 GitHub Personal Token

步骤：

访问 https://github.com/settings/tokens
点击 Generate new token (classic)
Token name: “Obsidian Digital Garden”
Expiration: 90 days（或 No expiration）
Select scopes: 勾选 repo 和 workflow
点击 Generate token
复制 token（之后看不到，务必保存）
粘贴到 Obsidian 插件设置中

⚠️ 注意：不要分享这个 token，它可以访问你的 GitHub 账户

发布设置

Base URL: https://username.github.io/digital-garden
# 或自定义域名：https://yourdomain.com

Site Name: "我的知识库"
Site Description: "关于编程和学习的笔记"

# 导航栏菜单
Navigation: |
  关于我 | 
  分类 | 
  标签

发布你的第一篇笔记

方式 1：发布单个笔记（推荐新手）

编写笔记

创建文件 first-note.md：

---
title: "我的第一篇笔记"
---

# 欢迎来到我的数字花园

这是我发布的第一篇笔记，内容可以自由编写。

## 特点

- 支持 **Markdown** 语法
- 支持 [[内部链接]]
- 支持代码块

\`\`\`javascript
console.log("Hello, Digital Garden!");
\`\`\`

发布笔记

打开命令面板：Ctrl+P（或 Cmd+P）
搜索 “Digital Garden: Publish single note”
选择要发布的笔记
等待上传完成

验证发布

访问 https://username.github.io/digital-garden/ 查看效果。

方式 2：发布整个库

发布所有笔记

命令面板 → “Digital Garden: Publish all notes”
选择要发布的笔记（可多选）
开始上传

注意：

私密笔记需要在 frontmatter 中标记
大型库首次上传可能耗时（几分钟到十几分钟）

方式 3：选择性发布

标记笔记为发布

在笔记 frontmatter 中添加：

---
title: "笔记标题"
published: true    # 发布此笔记
---

不添加或设置 published: false 则不发布。

自动发布设置

修改插件设置中的发布规则：

Use YAML frontmatter to determine which notes get published
✅ 启用此选项后，只有 published: true 的笔记才会发布

高级配置

自定义域名

使用自己的域名替代 GitHub Pages 默认域名

步骤 1：购买域名

访问 Namecheap、GoDaddy、阿里云等注册域名。

步骤 2：配置 DNS

方式 A：GitHub Pages 托管（推荐）

在域名提供商的 DNS 设置中添加：

CNAME 记录：
Name: @（或留空）
Value: username.github.io

或子域名：
Name: garden
Value: username.github.io

等待 DNS 传播（通常 5-30 分钟）。

方式 B：自定义 IP（适合有服务器的用户）

A 记录（IPv4）：
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

AAAA 记录（IPv6）：
2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

步骤 3：更新插件设置

Base URL: https://yourdomain.com

步骤 4：配置 HTTPS（自动）

GitHub Pages 自动为自定义域配置 SSL 证书，等待几分钟后访问 https://yourdomain.com 。

导航菜单自定义

编辑导航链接

在插件设置中修改：

Navigation Links:
主页 | /
关于 | /about
博客 | /blog
分类 | /categories

创建导航页面

创建文件 about.md：

---
title: "关于我"
---

# 关于我

简单介绍...

配置主题色

在 Obsidian 中调整

Settings → Community plugins → Digital Garden → Appearance

Primary Color: #5b8def      (链接颜色)
Accent Color: #e84d4d       (强调颜色)
Background Color: #ffffff   (背景色)
Text Color: #2b2b2b         (文字色)

或在网站级别自定义 CSS

在仓库中创建 public/custom.css：

:root {
  --primary-color: #5b8def;
  --accent-color: #e84d4d;
  --background: #f5f5f5;
  --text: #2b2b2b;
}

a {
  color: var(--primary-color);
}

code {
  background-color: var(--background);
}

自定义主题

修改全局样式

创建自定义 CSS 文件

打开仓库，编辑 .obsidian-garden/custom-styles.css
或在 Obsidian 中使用 Snippets

常用样式自定义

/* 代码块 */
pre {
  background-color: #2b2b2b;
  color: #f8f8f2;
  padding: 15px;
  border-radius: 5px;
  overflow-x: auto;
}

code {
  font-family: 'Monaco', 'Consolas', monospace;
  font-size: 14px;
}

/* 链接样式 */
a {
  color: #5b8def;
  text-decoration: none;
  border-bottom: 2px solid transparent;
  transition: border-color 0.3s;
}

a:hover {
  border-bottom-color: #5b8def;
}

/* 标题样式 */
h1, h2, h3 {
  border-left: 4px solid #e84d4d;
  padding-left: 10px;
  margin-top: 20px;
}

/* 引用块 */
blockquote {
  border-left: 4px solid #5b8def;
  padding-left: 15px;
  opacity: 0.85;
  font-style: italic;
}

/* 响应式表格 */
table {
  width: 100%;
  border-collapse: collapse;
  margin: 15px 0;
}

table th {
  background-color: #f0f0f0;
  padding: 10px;
  text-align: left;
}

table td {
  border: 1px solid #ddd;
  padding: 10px;
}

/* 移动设备适配 */
@media (max-width: 768px) {
  body {
    font-size: 16px;
  }
  
  h1 { font-size: 24px; }
  h2 { font-size: 20px; }
  h3 { font-size: 18px; }
}

更改字体

在 Obsidian 中更改

Settings → Appearance → Font

Font family: "Noto Sans CJK SC", -apple-system, BlinkMacSystemFont, sans-serif

或在 CSS 中指定

body {
  font-family: "Noto Sans CJK SC", "Segoe UI", sans-serif;
  line-height: 1.7;
  font-size: 16px;
}

code, pre {
  font-family: "Fira Code", "Consolas", monospace;
  font-size: 14px;
}

添加自定义主题

创建完整主题包

fork 官方仓库
修改 src/styles/theme.css
提交 PR 或自行部署

或使用社区主题

Digital Garden 社区已有多个主题：

Dark Garden（深色主题）
Light Forest（明亮主题）
Ocean（蓝色主题）

常见问题

Q1：发布后网站显示”404”？

原因：仓库未启用 GitHub Pages

解决：

进入仓库 Settings → Pages
检查 Source 是否为 “GitHub Actions”
如果为”None”，改为”GitHub Actions”
等待 1-2 分钟自动部署

Q2：更新笔记后网站没有变化？

原因：网站可能被浏览器缓存

解决：

硬刷新（Ctrl+Shift+R 或 Cmd+Shift+R）
打开浏览器开发工具禁用缓存
等待 GitHub Actions 完成部署（查看 Actions 标签）

Q3：Internal links（内部链接）无法工作？

原因：链接目标文件未发布

解决：

确保链接指向的文件也被发布：

# ✅ 正确
[[已发布的笔记]]
[[another-note]]

# ❌ 错误
[[private-note]]  (未标记为 published: true)
[[not-exists]]    (文件不存在)

Q4：中文文件名导致链接无法访问？

原因：URL 编码问题

解决：

# ✅ 推荐：使用英文文件名
first-note.md

在 frontmatter 中定义中文标题：
---
title: "我的第一篇笔记"
---

# ❌ 避免：中文文件名
我的笔记.md

Q5：如何隐藏某些笔记？

方式 1：frontmatter 标记

---
title: "私密笔记"
published: false  # 不发布
---

方式 2：在 .gitignore 中忽略

private/
draft/
*.tmp

Q6：如何添加评论功能？

使用 Giscus（GitHub Discussions）

在仓库 Settings → Discussions 中启用

然后在插件设置中配置：

Enable Comments: ✅
Comments Provider: Giscus
Repository: YOUR_USERNAME/digital-garden

Q7：网站加载很慢？

优化方案：

减少高分辨率图片

使用 Tinify（https://tinypng.com/）压缩图片

使用 Lazy Loading

![Image](/vault-assets/image.jpg){loading=lazy}

启用 CDN（如果自定义域名）
```
使用 Cloudflare 免费 CDN
```
删除不必要的插件依赖
```
减少 JavaScript 加载量
```

工作流示例

场景 1：个人博客

1. Obsidian 中写笔记（自动保存）
   ↓
2. 完成笔记，加上 frontmatter：
   ---
   title: "文章标题"
   published: true
   ---
   ↓
3. 命令面板 → Publish single note
   ↓
4. GitHub 自动部署（~2 分钟）
   ↓
5. 访问网站，文章已上线

场景 2：知识库分享

1. Obsidian 中维护笔记库
   ↓
2. 批量标记要发布的笔记：
   published: true
   ↓
3. Publish all notes
   ↓
4. 一键发布整个知识库

场景 3：同步多设备笔记

配合 Obsidian Git：

1. 在设备 A 编辑笔记
   ↓
2. Obsidian Git 自动同步到 GitHub
   ↓
3. 设备 B 自动拉取最新笔记
   ↓
4. Digital Garden 自动发布到网站

部署检查清单

📚 相关文档

obsidian-sync-and-deployment-guide - 整合多种方案的完整工作流