Obsidian + Quartz 4 数字花园完整工作流

概述

本文档介绍如何使用 Obsidian + Markdown + GitHub + Quartz 4 构建和维护个人数字花园（Digital Garden）的完整工作流程。

技术栈

Obsidian: 本地 Markdown 编辑器，提供强大的笔记管理功能
Markdown: 轻量级标记语言，便于编写和版本控制
GitHub: 代码托管和版本控制
Quartz 4: 静态网站生成器，将 Markdown 转换为精美的网站
Docker: 容器化部署，简化服务器配置

工作流程图

Obsidian (本地编辑)
    ↓ 编写笔记
Markdown 文件 (.md)
    ↓ Git commit & push
GitHub Repository
    ↓ 部署脚本
服务器 (Docker)
    ↓ Quartz 4 构建
静态网站 (https://notes.biyo.site)

Obsidian 配置

基础设置

1. 创建 Vault

# 克隆 Digital Garden 仓库
git clone https://github.com/username/digital-garden.git
cd digital-garden
 
# 在 Obsidian 中打开 content 文件夹作为 Vault

2. 推荐设置

文件与链接:

新建笔记位置: content/atlas 或对应分类文件夹
内部链接类型: 基于 Vault 根目录的相对路径
使用 Wiki 链接: ✅ 启用
自动更新内部链接: ✅ 启用

编辑器:

默认视图模式: 编辑模式
显示行号: ✅ 启用
折叠标题: ✅ 启用
严格换行: ✅ 启用

文件:

删除文件确认: ✅ 启用
默认存储附件位置: content/assets

文件夹结构

content/
├── atlas/              # 知识地图（主要笔记）
│   ├── ai/            # AI 相关笔记
│   │   ├── dify/      # Dify 工作流
│   │   ├── prompts/   # 提示词
│   │   └── learning/  # AI 学习笔记
│   ├── backend/       # 后端开发
│   ├── devops/        # 运维部署
│   └── mindset/       # 思维方式
├── journal/           # 日记
│   └── work/          # 工作日志
├── resources/         # 资源索引
│   └── tools/         # 工具推荐
├── side-projects/     # 副业项目
└── index.md           # 首页

笔记模板

DevOps 笔记模板

创建文件: templates/devops-note.md

---
title: {{title}}
date: {{date}}
tags:
  - devops
  - {{tag}}
---
 
## 问题背景
 
## 解决方案
 
### 步骤
 
1.
2.
3.
 
### 命令
 
\`\`\`bash
# 命令示例
\`\`\`
 
## 验证
 
\`\`\`bash
# 验证命令
\`\`\`
 
## 注意事项
 
-
 
## 相关文档
 
- [[]]

AI 笔记模板

创建文件: templates/ai-note.md

---
title: {{title}}
date: {{date}}
tags:
  - ai
  - {{category}}
---
 
## 工具/概念
 
## 使用场景
 
## 示例
 
\`\`\`
示例代码或提示词
\`\`\`
 
## 优缺点
 
### 优点
-
 
### 缺点
-
 
## 相关资源
 
-

Markdown 最佳实践

基础语法

# 一级标题
## 二级标题
### 三级标题
 
**粗体** *斜体* ~~删除线~~
 
- 无序列表项 1
- 无序列表项 2
 
1. 有序列表项 1
2. 有序列表项 2
 
[链接文本](https://example.com)
 
![图片描述](path/to/image.png)
 
`行内代码`
 
\`\`\`language
代码块
\`\`\`
 
> 引用文本

Quartz 特定语法

Wiki 链接

# 基础链接
[[目标笔记]]
 
# 带显示文本的链接
[[目标笔记|显示文本]]
 
# 链接到标题
[[目标笔记#标题|标题]]
 
# 嵌入其他笔记
![[目标笔记]]

Frontmatter

---
title: 笔记标题
date: 2026-01-02
tags:
  - tag1
  - tag2
aliases:
  - 别名1
  - 别名2
draft: false
---

字段说明:

title: 笔记标题（显示在网页标题）
date: 创建/更新日期
tags: 标签列表（用于分类和搜索）
aliases: 别名（可以用别名链接到此笔记）
draft: 是否为草稿（true 则不发布）

高级功能

Callout（提示框）:

> [!note] 笔记
> 
> 这是一个笔记提示框
 
> [!tip] 提示
> 
> 这是一个提示框
 
> [!warning] 警告
> 
> 这是一个警告框
 
> [!danger] 危险
> 
> 这是一个危险警告框
 
> [!info] 信息
> 
> 这是一个信息框

折叠内容:

<details>
<summary>点击展开</summary>
 
折叠的内容...
 
</details>

表格:

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |

图片管理

本地图片

# 相对路径
![图片描述](../assets/image.png)
 
# 从 assets 文件夹
![图片描述](/assets/image.png)

图床（推荐）

使用图床服务，避免仓库体积过大：

![图片描述](https://i.imgur.com/xxx.png)

Obsidian 图片插件

安装 Image Auto Upload 插件：

自动上传粘贴的图片到图床
自动替换为图床链接

GitHub 工作流

基础 Git 操作

日常提交流程

# 1. 查看更改
git status
git diff
 
# 2. 添加文件
git add content/
git add .  # 添加所有更改
 
# 3. 提交
git commit -m "add: 新增 xxx 笔记"
 
# 4. 推送到 GitHub
git push

提交信息规范

使用语义化提交信息：

# 新增内容
git commit -m "add: 新增 Docker 部署笔记"
 
# 更新内容
git commit -m "update: 更新 Nginx 配置说明"
 
# 修复错误
git commit -m "fix: 修复链接错误"
 
# 文档相关
git commit -m "docs: 更新 README"
 
# 重构
git commit -m "refactor: 重组文件夹结构"
 
# 删除内容
git commit -m "remove: 删除过期笔记"

.gitignore 配置

# Obsidian 配置（个人配置不提交）
.obsidian/workspace
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/hotkeys.json
.obsidian/appearance.json
.obsidian/graph.json
 
# 但保留公共配置
!.obsidian/app.json
!.obsidian/core-plugins.json
!.obsidian/community-plugins.json
 
# Node modules
node_modules/
 
# 构建产物
public/
.quartz-cache/
 
# 系统文件
.DS_Store
Thumbs.db
 
# 临时文件
*.tmp
*.log
 
# 草稿（可选）
drafts/

分支策略

主分支（main）

发布版本
保持稳定
所有更改需要测试

工作分支

# 创建新笔记分支
git checkout -b feature/new-notes
 
# 编辑笔记...
 
# 提交并合并
git add .
git commit -m "add: 新增笔记"
git checkout main
git merge feature/new-notes
git push

GitHub Actions（可选）

自动化部署配置：

创建 .github/workflows/deploy.yml:

name: Deploy Quartz
 
on:
  push:
    branches: [ main ]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build site
        run: npx quartz build
 
      - name: Deploy to server
        run: |
          # 部署脚本

Quartz 4 配置

基础配置

quartz.config.ts

import { QuartzConfig } from "./quartz/cfg"
import * as Plugin from "./quartz/plugins"
 
const config: QuartzConfig = {
  configuration: {
    pageTitle: "🌱 Digital Garden",
    enableSPA: true,
    enablePopovers: true,
    analytics: {
      provider: "plausible",
    },
    locale: "zh-CN",
    baseUrl: "notes.biyo.site",
    ignorePatterns: ["private", "templates", ".obsidian"],
    defaultDateType: "created",
    theme: {
      typography: {
        header: "Schibsted Grotesk",
        body: "Source Sans Pro",
        code: "IBM Plex Mono",
      },
      colors: {
        lightMode: {
          light: "#faf8f8",
          lightgray: "#e5e5e5",
          gray: "#b8b8b8",
          darkgray: "#4e4e4e",
          dark: "#2b2b2b",
          secondary: "#284b63",
          tertiary: "#84a59d",
          highlight: "rgba(143, 159, 169, 0.15)",
        },
        darkMode: {
          light: "#161618",
          lightgray: "#393639",
          gray: "#646464",
          darkgray: "#d4d4d4",
          dark: "#ebebec",
          secondary: "#7b97aa",
          tertiary: "#84a59d",
          highlight: "rgba(143, 159, 169, 0.15)",
        },
      },
    },
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.CreatedModifiedDate(),
      Plugin.Latex({ renderEngine: "katex" }),
      Plugin.SyntaxHighlighting(),
      Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }),
      Plugin.GitHubFlavoredMarkdown(),
      Plugin.TableOfContents(),
      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
      Plugin.Description(),
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.AliasRedirects(),
      Plugin.ComponentResources(),
      Plugin.ContentPage(),
      Plugin.FolderPage(),
      Plugin.TagPage(),
      Plugin.ContentIndex({
        enableSiteMap: true,
        enableRSS: true,
      }),
      Plugin.Assets(),
      Plugin.Static(),
      Plugin.NotFoundPage(),
    ],
  },
}
 
export default config

自定义主题

修改颜色

编辑 quartz/styles/custom.scss:

// 自定义颜色
:root {
  --light: #faf8f8;
  --lightgray: #e5e5e5;
  --gray: #b8b8b8;
  --darkgray: #4e4e4e;
  --dark: #2b2b2b;
  --secondary: #284b63;
  --tertiary: #84a59d;
  --highlight: rgba(143, 159, 169, 0.15);
}
 
// 自定义字体大小
body {
  font-size: 16px;
  line-height: 1.6;
}
 
// 自定义标题样式
h1 {
  font-size: 2em;
  border-bottom: 2px solid var(--lightgray);
  padding-bottom: 0.3em;
}
 
// 自定义链接样式
a {
  color: var(--secondary);
  text-decoration: none;
 
  &:hover {
    text-decoration: underline;
  }
}
 
// 自定义代码块
pre {
  border-radius: 8px;
  padding: 1em;
}
 
// 自定义表格
table {
  border-collapse: collapse;
  width: 100%;
 
  th, td {
    border: 1px solid var(--lightgray);
    padding: 0.5em;
  }
 
  th {
    background-color: var(--lightgray);
  }
}

搜索配置

启用全文搜索：

// quartz.config.ts
plugins: {
  // ...
  emitters: [
    Plugin.ContentIndex({
      enableSiteMap: true,
      enableRSS: true,
      rssLimit: 10,
      rssFullHtml: true,
      includeEmptyFiles: false,
    }),
    // ...
  ]
}

Graph View（关系图）

配置知识图谱显示：

// quartz.config.ts
components: {
  beforeBody: [
    Component.Breadcrumbs(),
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TagList(),
  ],
  left: [
    Component.PageTitle(),
    Component.MobileOnly(Component.Spacer()),
    Component.Search(),
    Component.Darkmode(),
    Component.DesktopOnly(Component.Explorer()),
  ],
  right: [
    Component.Graph(),
    Component.DesktopOnly(Component.TableOfContents()),
    Component.Backlinks(),
  ],
}

部署流程

本地测试

# 1. 安装依赖
npm install
 
# 2. 本地预览
npx quartz build --serve
 
# 3. 访问 http://localhost:8080

服务器部署

使用部署脚本（推荐）

# 完整部署（推送 + 服务器构建）
.\deploy\scripts\deploy.ps1 -Action app
 
# 本地测试部署
.\deploy\scripts\deploy.ps1 -Action local
 
# 查看日志
.\deploy\scripts\deploy.ps1 -Action logs
 
# 查看状态
.\deploy\scripts\deploy.ps1 -Action status

Docker 部署配置

docker-compose.yml:

services:
  app:
    build: .
    container_name: digital-garden
    ports:
      - "8084:80"
    restart: always
    environment:
      - NODE_ENV=production

Dockerfile:

# Build Stage
FROM node:22-alpine AS builder
 
RUN apk add --no-cache coreutils
 
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci
 
COPY . .
RUN npx quartz build
 
# Run Stage
FROM nginx:alpine
 
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=builder /app/public /usr/share/nginx/html
 
EXPOSE 80
 
CMD ["nginx", "-g", "daemon off;"]

Nginx 配置

nginx.conf:

server {
    listen 80;
    server_name localhost;
 
    root /usr/share/nginx/html;
    index index.html;
 
    # Clean URLs support
    location / {
        try_files $uri $uri.html $uri/ /404.html;
    }
 
    # Gzip compression
    gzip on;
    gzip_types text/plain text/css text/xml text/javascript
               application/javascript application/xml+rss application/json;
 
    # Cache static assets
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
 
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
}

完整工作流示例

场景 1: 创建新笔记

# 1. 在 Obsidian 中创建新笔记
# 文件: content/atlas/devops/docker-best-practices.md
 
# 2. 编写内容（使用模板）
# - 添加 frontmatter
# - 编写正文
# - 添加标签
# - 添加内部链接
 
# 3. 保存并检查
git status
git diff
 
# 4. 提交到 Git
git add content/atlas/devops/docker-best-practices.md
git commit -m "add: Docker 最佳实践笔记"
 
# 5. 推送到 GitHub
git push
 
# 6. 部署到服务器
.\deploy\scripts\deploy.ps1 -Action app
 
# 7. 访问网站验证
# https://notes.biyo.site/atlas/devops/docker-best-practices

场景 2: 更新现有笔记

# 1. 在 Obsidian 中打开笔记
# 2. 编辑内容
# 3. 保存
 
# 4. 查看更改
git diff content/atlas/devops/nginx-https-setup.md
 
# 5. 提交
git add content/atlas/devops/nginx-https-setup.md
git commit -m "update: 更新 Nginx HTTPS 配置说明"
 
# 6. 推送并部署
git push
.\deploy\scripts\deploy.ps1 -Action app

场景 3: 批量创建笔记

# 1. 在 Obsidian 中创建多个笔记
# 2. 编写内容
# 3. 保存所有文件
 
# 4. 查看所有更改
git status
 
# 5. 批量添加
git add content/
 
# 6. 提交
git commit -m "add: 新增 AI 工具使用笔记（5篇）"
 
# 7. 推送部署
git push
.\deploy\scripts\deploy.ps1 -Action app

场景 4: 重构笔记结构

# 1. 在 Obsidian 中移动文件
# （Obsidian 会自动更新内部链接）
 
# 2. 使用 Git 查看更改
git status
git diff
 
# 3. 提交重构
git add .
git commit -m "refactor: 重组 AI 笔记分类结构"
 
# 4. 推送部署
git push
.\deploy\scripts\deploy.ps1 -Action app

性能优化

图片优化

# 使用 tinypng 或 squoosh 压缩图片
# 推荐尺寸:
# - 文章配图: 1200px 宽
# - 缩略图: 600px 宽
 
# 使用 WebP 格式
# - 更小的文件体积
# - 更好的压缩率

构建优化

# 增量构建（仅构建修改的文件）
npx quartz build --incremental
 
# 清理缓存后重新构建
rm -rf .quartz-cache
npx quartz build

部署优化

# 使用 GitHub Actions 自动部署
# 推送到 main 分支自动触发构建

备份策略

1. Git 版本控制

所有笔记都在 Git 中有完整历史记录：

# 查看历史记录
git log --oneline
 
# 恢复到特定版本
git checkout <commit-hash> -- <file>
 
# 查看文件历史
git log -p <file>

2. GitHub 自动备份

每次推送都会备份到 GitHub
可以在 GitHub 上查看和恢复历史版本

3. 本地备份（可选）

# 定期创建备份
tar -czf backup-$(date +%Y%m%d).tar.gz content/
 
# 或使用同步工具
# - OneDrive
# - Dropbox
# - iCloud

4. Obsidian 文件恢复

启用 Obsidian 的文件恢复插件：

设置 → 核心插件 → 文件恢复
保留历史记录天数: 30天

协作工作流

多人协作

# 1. 每次开始工作前拉取最新更改
git pull
 
# 2. 创建自己的工作分支
git checkout -b feature/your-name-topic
 
# 3. 编写笔记并提交
git add .
git commit -m "add: your changes"
 
# 4. 推送分支
git push origin feature/your-name-topic
 
# 5. 在 GitHub 上创建 Pull Request
# 6. Code Review 通过后合并到 main

冲突解决

# 如果出现冲突
git pull
# 手动解决冲突文件
git add .
git commit -m "fix: resolve conflicts"
git push

常见问题

问题 1: Wiki 链接不生效

原因: Quartz 需要特定的链接格式

解决:

# 错误
[[content/atlas/devops/note]]
 
# 正确
[[devops/note]]
或
[[note]]  # 如果文件名唯一

问题 2: 图片无法显示

原因: 路径不正确

解决:

# 使用相对路径
![](../assets/image.png)
 
# 或使用绝对路径
![](/assets/image.png)
 
# 或使用图床
![](https://i.imgur.com/xxx.png)

问题 3: 中文文件名乱码

原因: 编码问题

解决:

# 运行编码检查脚本
.\scripts\check-encoding.ps1 -Fix
 
# 确保 Git 配置
git config --global core.quotePath false

问题 4: 构建失败

原因: 可能是语法错误或插件问题

解决:

# 1. 检查日志
docker logs digital-garden
 
# 2. 本地测试
npx quartz build
 
# 3. 清理缓存重试
rm -rf .quartz-cache node_modules
npm install
npx quartz build

问题 5: 部署后样式错乱

原因: 缓存问题

解决:

# 1. 清理浏览器缓存
Ctrl + F5 (强制刷新)
 
# 2. 服务器重建
.\deploy\scripts\deploy.ps1 -Action app

高级技巧

1. 使用 Dataview 动态内容

# 最近更新的笔记
\`\`\`dataview
TABLE date as "日期", tags as "标签"
FROM "content/atlas"
SORT date DESC
LIMIT 10
\`\`\`
 
# 特定标签的笔记
\`\`\`dataview
LIST
FROM #devops
SORT file.name ASC
\`\`\`

2. 创建笔记索引

创建 content/atlas/index.md:

---
title: 知识地图
---
 
## AI
 
- [[ai/dify/dify-custom-tool|Dify 自定义工具]]
- [[ai/prompts/ios-app-prototype-designer|iOS 原型设计提示词]]
 
## DevOps
 
- [[devops/nginx-https-setup|Nginx HTTPS 配置]]
- [[devops/docker-best-practices|Docker 最佳实践]]
 
## Backend
 
- [[backend/coding-standards|代码规范]]

3. 使用别名

---
title: Docker 容器化
aliases:
  - Docker
  - 容器
  - Container
---

现在可以用 [[Docker]] 或 [[容器]] 链接到这篇笔记。

4. 草稿管理

---
title: 未完成的笔记
draft: true
---

设置 draft: true 的笔记不会被发布。

5. 使用快捷键

Obsidian 常用快捷键:

Ctrl/Cmd + N: 新建笔记
Ctrl/Cmd + O: 快速打开
Ctrl/Cmd + P: 命令面板
Ctrl/Cmd + E: 切换编辑/预览
Ctrl/Cmd + [: 插入链接
Ctrl/Cmd + K: 插入外部链接

6. 使用标签系统

---
tags:
  - devops/docker
  - tutorial
  - beginner
---

使用 / 创建嵌套标签，便于分类管理。

监控和分析

网站分析

使用 Google Analytics 或 Plausible：

// quartz.config.ts
analytics: {
  provider: "google",
  tagId: "G-XXXXXXXXXX",
}

监控指标

关注以下指标：

页面访问量
热门笔记
搜索关键词
用户来源

SEO 优化

---
title: 具体明确的标题
description: 简短的描述（150字以内）
tags:
  - 相关关键词
---

最佳实践总结

内容组织

使用清晰的文件夹结构
- 按主题分类（atlas/ai, atlas/devops）
- 避免嵌套过深（最多3层）
使用一致的命名规范
- 小写字母 + 连字符（docker-best-practices.md）
- 避免特殊字符和空格
添加完整的 Frontmatter
- title, date, tags 必填
- 使用有意义的标签

内容编写

结构化内容
- 使用清晰的标题层级
- 添加目录（Quartz 自动生成）
- 使用列表和表格
内部链接
- 主动链接相关笔记
- 构建知识网络
代码示例
- 使用代码块并指定语言
- 添加注释说明
定期更新
- 更新过时信息
- 添加新的发现

版本控制

有意义的提交信息
- 使用语义化提交
- 描述具体更改
小步提交
- 每次提交一个主题
- 便于回滚和查找
定期推送
- 每天至少推送一次
- 避免丢失工作

工作习惯

每日回顾
- 整理当天笔记
- 补充完善内容
每周整理
- 重构笔记结构
- 删除过时内容
每月总结
- 创建月度总结笔记
- 提炼核心知识点

更新记录

2026-01-02: 创建完整的 Obsidian + Quartz 4 工作流指南

Quartz 4

Explorer