Quartz 使用教程：把 Obsidian 笔记变成网站

本篇重点讲网页笔记的搭建——怎么让 Obsidian 里的 Markdown 笔记变成一个能在浏览器打开的网站。同步与自动化见：Quartz/部署与更新；排错见：Quartz/常见问题。

一、Quartz 是什么

Quartz 是一个开源静态站点生成器，专门把 Obsidian 仓库「编译」成网站。它保留你最在意的几样东西：

双链（[[笔记名]]）与反向链接
全文搜索、标签、关系图、暗色模式
部署后，手机 / 平板 / 电脑用浏览器打开就能看

核心理念一句话：你在 Obsidian 里照常写，Quartz 负责把它变成网站。 你完全不用租服务器。

二、整体架构（先建立心智模型）

本方案的关键决策：不用 git 子模块，笔记在 Cloudflare 构建时直接用 token 拉取。这样能避开「私有子模块在 Cloudflare 上拉不下来」这个大坑（详见 Quartz/常见问题）。

E:\文档\Obsidian Vault   （本地写笔记，= GitHub 的 Obisidian-Note 仓库，私有）
        │ Obsidian Git 自动 push
GitHub: Obisidian-Note (main 分支)
        │ push 触发 GitHub Actions
        │   → curl 触发 Cloudflare Deploy Hook
Cloudflare Pages: quartz-459  （绑定 quartz 仓库的 v5 分支）
        │ Deploy Hook 触发重新构建
        │ Build command: 用 GH_PAT 把 Obisidian-Note 克隆到 content/ → npx quartz build
public/ 静态站 (HTML/CSS/JS)
        │ Cloudflare 上线
notes.cijun.win  （任意设备浏览器访问）

链路里有两个容易混的密钥：GH_PAT（存在 Cloudflare，让它能拉你的私有笔记）和 CF_DEPLOY_HOOK（存在 GitHub，让它能叫 Cloudflare 重新构建）。两者的作用和配置位置见 Quartz/部署与更新 > 0) 两个密钥先分清（最容易混）。

也就是：Obsidian 写 → GitHub 推 → Cloudflare 自动上线。你只在一个地方写，其余全自动。

涉及两个 GitHub 仓库，别搞混：

Obisidian-Note（私有，main 分支）= 笔记真相源，你日常写的地方。

quartz（v5 分支）= Quartz 工程；它的 content/ 平时是空的，构建时才去拉笔记。

三、本地环境准备

只需要 Node.js 和 npm（已装可跳过）：

到 https://nodejs.org 装 LTS 版
验证：终端跑 node -v 和 npm -v 都有版本号即可

四、获取 Quartz 项目

推荐用官方初始化命令（新手最不容易出错，等于自动帮你 clone 并初始化 git）：

# 新建一个目录放 Quartz 项目，例如 D:\Quartz
cd D:\Quartz
npx create-quartz@latest

它会交互式地问你仓库名、是否推到 GitHub，按提示走完即可。装依赖：

cd quartz
npm install

最终你要有一个你自己账号下的 Quartz 仓库（这里是 CIJUNBUGUILU/quartz，部署分支 v5），Cloudflare 才能拉到它。本机这个目录只在你改 Quartz 自身配置（主题、插件）时才用，平时写笔记不用碰它。

五、配置文件（Quartz v5 是 YAML）

当前使用的是 Quartz v5。v5 已弃用 v4 的 quartz.config.ts，改用 YAML。

基于模板复制出配置文件：

Copy-Item quartz.config.default.yaml quartz.config.yaml

打开 quartz.config.yaml，改这几处：

# 自定义域名（不带 https://，不带末尾斜杠）
baseUrl: notes.cijun.win
 
# 网站标题
pageTitle: "CIJUN 的笔记"
 
# 忽略规则：默认已含 .obsidian，你的 Obsidian 本地配置不会被发出去
ignorePatterns:
  - .obsidian
  - .git
  - node_modules

baseUrl 设错会导致 CSS/JS 资源路径错误、页面样式崩，务必核对。

启用主题（可选但推荐）

本站用的是 tokyo-night 深色科技风，在 quartz.config.yaml 的 plugins → transformers 里把 @quartz-themes/core 的 enabled 设为 true 即可。全局样式微调放在 quartz/styles/custom.scss。

六、笔记放在哪（关键：不用子模块）

Quartz 的笔记放在 content/。 但本方案不使用 git 子模块——content/ 在仓库里是空的（已被 .gitignore 忽略），笔记在 Cloudflare 构建时由 Build command 用 token 直接拉取。

所以你在本地不需要把笔记挂进 Quartz 项目。日常只做一件事：在 E:\文档\Obsidian Vault 写笔记并让 Obsidian Git 推到 GitHub。构建那一步交给 Cloudflare。

唯一要确保的是：笔记仓库根目录有 index.md（见下节），否则网站首页 404。

七、必须有首页 index.md

Quartz 把 content/index.md 当作首页。你的笔记仓库根目录必须有这个文件，否则访问 notes.cijun.win/ 会 404。

文件位置：Obisidian-Note/index.md（即 E: 仓库根目录，不是子文件夹）
内容随意，例如：

---
title: CIJUN 的笔记
---
 
欢迎来到我的笔记站。

八、本地预览

npx quartz build --serve

终端会打印地址（v5 默认 http://localhost:8080），浏览器打开检查效果。改了笔记后 Quartz 有热重载，刷新即可。

本地预览时，如果 content/ 是空的（本方案它平时为空），先手动把笔记复制进 content/，或临时 git clone 一下，预览完后再删掉——别提交进 quartz 仓库。

九、笔记书写约定

双链：[[另一篇笔记]] 互相引用，Quartz 自动生成跳转和反向链接。
标签：在文件顶部 frontmatter 写 tags: [教程]，可在侧边栏按标签浏览。
图片 / 附件：放进笔记同目录，用相对路径引用，例如 ![图](./img/1.png)；不要引用 file:// 绝对路径。
frontmatter：文件顶部用 --- 包裹的区块可写 title、tags 等元数据。

十、下一步

想让笔记推上去就自动上线、搞懂同步链路 → Quartz/部署与更新
遇到报错或页面不对 → Quartz/常见问题

CIJUN的笔记

Explorer

Quartz 使用教程