Quartz + GitHub Pages：把 Obsidian 笔记变成数字花园

频道很快会推出一期关于设置 Obsidian Publish 的视频；在此之前，你可以先阅读这篇设置教程：

引言：从笔记到数字花园

想象一下，你在 Obsidian 里有几百条笔记，是你个人的知识档案，已经积累了几个月甚至几年。这些笔记彼此相连，蕴含着宝贵的见解，不仅对你有用，也可能对别人有帮助。

问题在于，它们被锁在你的应用里，外界无从看到。Quartz 可以解决这个问题：它能把你的笔记变成一个完整的网站，也就是你自己的数字花园。

什么是数字花园？

数字花园是一种发布知识的理念，和传统博客有根本的不同：

博客是按时间顺序排列的成品文章流
数字花园是让想法不断生长的活空间

在数字花园里，你的笔记可以是：

🌱 幼苗：原始的想法、草稿
🌿 萌芽：正在打磨中的想法
🌳 常青：已经完成的笔记

这个理念消除了完美主义带来的压力：你可以发布尚未成形的想法，并在公开的过程中不断完善它们。

Quartz 是什么，为什么它比其他方案更好

Quartz 是一个静态网站生成器，专为处理 Markdown 格式的笔记而打造。简单来说：Quartz 会把你在 Obsidian 里的文件变成一个漂亮的网站，并保留所有链接、关系图谱和搜索功能。

Quartz 相比其他方案的优势：

对比项	Obsidian Publish	Notion Sites	Quartz
费用	$10/月	免费	免费
维基链接	✅	❌	✅
关系图谱	✅	❌	✅
完全掌控	❌	❌	✅
在俄罗斯可用	❌（Cloudflare）	✅	✅
速度	⚡⚡	⚡	⚡⚡⚡

Quartz 的技术优势：

✅ 与 Obsidian 完全兼容：维基链接、反向链接、标注块（callout） ✅ 静态生成：网站运行快速、稳定 ✅ GitHub Pages：免费托管，全球都能访问 ✅ 版本管理：所有修改历史都保存在 Git 中 ✅ 独立自主：你的数据只属于你

什么是 Quartz Syncer？

Quartz Syncer 是一个 Obsidian 插件，能把使用 Quartz 的所有技术环节自动化。现在发布内容就像用 Obsidian Publish 一样简单：

在 Obsidian 里写好一条笔记
通过插件标记为待发布
点击“同步”
网站自动更新

Quartz Syncer 的功能：

🔄 与 GitHub 仓库自动同步 📝 直接在 Obsidian 里发布，就像 Obsidian Publish 一样 📁 选择性发布：可以选择特定的文件夹 🔌 支持 Obsidian 插件：Dataview、模板等 ⚡ 即时编译：可处理动态内容

这实际上找回了 Obsidian Publish 的便利，同时还能拥有完全的控制权，并且全球都能访问！

准备工作

必备工具

开始之前，请确认你已经有：

一个存有笔记的 Obsidian
一个 GitHub 账号（可在 github.com 免费注册）
Quartz Syncer 插件（通过 Obsidian 的第三方插件安装）

进阶方法的可选工具：

GitHub Desktop（下载）：Git 的图形界面
Node.js（下载）：Quartz 的运行环境

🟢 简单方法：通过 GitHub 网页界面

**适合：**想尝试 Quartz、又不想安装额外程序的人 **设置时间：**30-45 分钟 **难度：**和注册一个社交媒体账号差不多

第 1 步：创建 GitHub 仓库

在浏览器中打开 Quartz 模板
点击绿色的 “使用此模板” 按钮 → “创建新仓库”
配置仓库：
- 仓库名称：my-digital-garden（或任何其他名称）
- 描述：My digital garden based on Obsidian
- 可见性：公开（免费使用 GitHub Pages 的必要条件）
点击 “创建仓库”

第 2 步：启用 GitHub Pages

进入你仓库的“设置”
在左侧菜单中找到 Pages 栏目
选择 Source：GitHub Actions（不是“从分支部署”！）
保存设置

GitHub 会自动开始构建网站。5-10 分钟后，你的网站就可以通过以下地址访问：https://username.github.io/repository-name

第 3 步：在 Obsidian 中安装 Quartz Syncer

打开 Obsidian → 设置 → 第三方插件
搜索并安装 “Quartz Syncer”
在已安装插件列表中启用该插件

第 4 步：配置 Quartz Syncer

打开 Quartz Syncer 插件的设置
选择“连接到 GitHub”
按照说明创建 GitHub 令牌：
- 进入 GitHub → 设置 → 开发者设置 → 个人访问令牌
- 创建一个对你的仓库拥有权限的新令牌
- 把令牌复制到插件设置中
从列表中选择你的仓库
配置需要同步的文件夹

第 5 步：第一次发布

挑选 2-3 条笔记用于测试
确认它们内容完整、链接正确
在 Quartz Syncer 插件中点击“同步”按钮
等待同步完成（1-2 分钟）
5-10 分钟后查看网站

简单方法的优点：

✅ 不需要安装额外的程序 ✅ 所有设置都通过网页界面完成 ✅ 适合快速测试 ✅ 入门门槛极低

简单方法的局限：

❌ 自定义设计的空间有限 ❌ 添加自己的样式和脚本比较困难 ❌ 没有本地副本，无法离线工作

🟡 进阶方法：通过 GitHub Desktop

**适合：**想要最大程度的控制权和灵活性的人 **设置时间：**1-2 小时 **难度：**和学习 Photoshop 这类新软件差不多

第 1 步：安装必备工具

1.1 GitHub Desktop

下载 GitHub Desktop
安装并登录你的 GitHub 账号
熟悉一下基本界面（5 分钟）

1.2 Node.js

下载 Node.js LTS 版本
使用默认设置安装
通过命令行检查是否安装成功：
```
node --version
npm --version
```

第 2 步：设置本地项目

2.1 克隆 Quartz

打开 GitHub Desktop
点击文件 → 克隆仓库 → URL
粘贴 https://github.com/jackyzha0/quartz.git
在你的电脑上选择项目文件夹
点击克隆

2.2 创建你自己的仓库

在 GitHub 上创建一个新仓库（方法与简单方法相同）
在 GitHub Desktop 中点击仓库 → 仓库设置
把 Remote URL 改成你的新仓库
发布更改：仓库 → 推送 origin

第 3 步：Quartz 的基本设置

3.1 安装依赖

打开命令行（终端/命令提示符）
进入项目文件夹：
```
cd path/to/your/quartz
```
安装依赖：
```
npm install
```

3.2 配置设置

用任意文本编辑器打开 quartz.config.ts 文件

修改主要参数：

const config: QuartzConfig = {  configuration: {    pageTitle: "My digital garden",    enableSPA: true,    enablePopovers: true,    analytics: {      provider: "plausible", // or "google"    },    locale: "en-US",    baseUrl: "https://username.github.io/repository-name",    ignorePatterns: [      "private",      "templates",       ".obsidian",      "drafts"    ],  },}

第 4 步：设置自动发布

4.1 GitHub Actions

Quartz 自带现成的配置，位于 .github/workflows/deploy.yml 文件中。它会自动：

在每次推送时构建网站
通过 GitHub Pages 发布
在 5-10 分钟内更新网站

4.2 启用 GitHub Pages

进入 GitHub 上该仓库的“设置”
找到 Pages 栏目
选择 Source：GitHub Actions
保存设置

第 5 步：通过 Quartz Syncer 与 Obsidian 集成

5.1 配置插件

在 Obsidian 中安装 Quartz Syncer
在插件设置中选择 “本地仓库”
指定本地 Quartz 文件夹的路径
配置需要同步的文件夹

5.2 发布流程

现在的发布流程是这样的：

你在 Obsidian 里写一条笔记
你通过 Quartz Syncer 同步它
插件会自动把文件复制到 content 文件夹
GitHub Desktop 会显示这些更改
你通过 GitHub Desktop 提交并推送
GitHub Actions 会自动更新网站

高级方法的优势:

✅ 完全掌控设计和功能 ✅ 本地开发——可以离线测试修改 ✅ 自定义——添加你自己的样式、脚本和插件 ✅ 性能——按你的需求进行优化 ✅ 备份——所有文件都有本地副本

可能遇到的困难:

❌ 需要安装额外的程序 ❌ 要学习更多技术细节 ❌ 对于简单任务来说可能有点大材小用

自定义和优化站点

配置外观

quartz.config.ts 中的基本设置

theme: {
  cdnCaching: true,
  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)",
    },
  },
},

创建自定义样式

创建文件 quartz/styles/custom.scss

添加你自己的样式:

// Font settingsbody {  font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;}// Heading stylesh1, h2, h3 {  color: var(--dark);  font-weight: 600;}// Custom callouts.callout[data-callout="tip"] {  border-color: #00d4aa;  background-color: rgba(0, 212, 170, 0.1);}

配置组件

quartz.layout.ts 中的页面结构

export const defaultContentPageLayout: PageLayout = {
  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.DesktopOnly(Component.TableOfContents()),
    Component.Backlinks(),
  ],
}

SEO 优化

笔记的元数据

在笔记开头添加 YAML frontmatter:

---
title: "The full article title"
description: "A short description for search engines"
tags: ["obsidian", "productivity", "pkm"]
date: 2024-01-15
draft: false
---

设置统计分析

在 quartz.config.ts 中:

analytics: {
  provider: "google",
  tagId: "G-XXXXXXXXXX", // your Google Analytics ID
},

数字花园的最佳实践

1. 内容结构化

创建导航枢纽(MOC)

# 🧠 Productivity and knowledge management
 
This is my navigation hub for the topic of productivity.
 
## 🌱 Developing ideas
- [[The Zettelkasten method]]
- [[Second brains]]
- [[Digital minimalism]]
 
## 🌳 Mature concepts  
- [[PARA Method]]
- [[Getting Things Done]]
- [[Principles of effective work with information]]
 
## 🛠 Tools
- [[Obsidian setup]]
- [[Notion vs Obsidian]]
- [[Quartz for publishing]]

2. 标签与链接体系

高效的标签:

#seedling——用于刚冒出来的新想法
#developing——用于正在推进的想法
#evergreen——用于已经完成的笔记
#public——用于可以发布的笔记
#private——用于个人笔记(从同步中排除)

创建链接:

使用双向链接 [[Note title]] 来构建知识网络
添加上下文 [[Note|在讨论的语境中]]
链接到章节 [[Note#a-specific-section|A specific section]]

3. 发布工作流

每周更新的固定流程:

周一:回顾本周新增的笔记
周三:完善 2-3 篇 seedling 笔记
周五:通过 Quartz Syncer 发布更新
周日:分析统计数据并做好计划

笔记的完善过程:

🌱 Seedling → 🌿 Sapling → 🌳 Evergreen
     ↓            ↓           ↓
Raw idea → Structuring → Publishing
(private)    (adding         (open
              links,          access)
              examples)

4. 与读者互动

添加联系方式

创建文件 content/contact.md:

# Get in touch with me
 
If these notes were useful or you have questions:
 
- 📧 Email: your@email.com  
- 💬 Telegram: @username
- 🐦 Twitter: @username
- 💼 LinkedIn: /in/username
 
## Feedback is welcome!
 
This digital garden grows thanks to interaction. 
Don't hesitate to share your thoughts and ideas.

Elton Labs

Quartz + GitHub Pages：把 Obsidian 笔记变成数字花园

引言：从笔记到数字花园

什么是数字花园？

Quartz 是什么，为什么它比其他方案更好

Quartz 相比其他方案的优势：

Quartz 的技术优势：

什么是 Quartz Syncer？

Quartz Syncer 的功能：

准备工作

必备工具

进阶方法的可选工具：

🟢 简单方法：通过 GitHub 网页界面

第 1 步：创建 GitHub 仓库

第 2 步：启用 GitHub Pages

第 3 步：在 Obsidian 中安装 Quartz Syncer

第 4 步：配置 Quartz Syncer

第 5 步：第一次发布

简单方法的优点：

简单方法的局限：

🟡 进阶方法：通过 GitHub Desktop

第 1 步：安装必备工具

1.1 GitHub Desktop

1.2 Node.js

第 2 步：设置本地项目

2.1 克隆 Quartz

2.2 创建你自己的仓库

第 3 步：Quartz 的基本设置

3.1 安装依赖

3.2 配置设置

第 4 步：设置自动发布

4.1 GitHub Actions

4.2 启用 GitHub Pages

第 5 步：通过 Quartz Syncer 与 Obsidian 集成

5.1 配置插件

5.2 发布流程

高级方法的优势:

可能遇到的困难:

自定义和优化站点

配置外观

quartz.config.ts 中的基本设置

创建自定义样式

配置组件

quartz.layout.ts 中的页面结构

SEO 优化

笔记的元数据

设置统计分析

数字花园的最佳实践

1. 内容结构化

推荐的文件夹结构:

创建导航枢纽(MOC)

2. 标签与链接体系

高效的标签:

创建链接:

3. 发布工作流

每周更新的固定流程:

笔记的完善过程:

4. 与读者互动

添加联系方式