NeoXmind 数字花园

使用Quartz 4 发布 Obsidian

23分钟阅读

部署完成后的日常使用（速查）

初次部署完成后，日常只需重复以下操作：

  1. 在 Obsidian 里写好笔记
  2. 把要公开的笔记复制到 content/ 目录
  3. 终端运行 npx quartz sync —— 自动构建并推送，GitHub Actions 自动更新站点

日常工作流

常用命令

操作命令
本地预览（热更新）npx quartz build --serve
发布更新到线上npx quartz sync
仅本地构建npx quartz build

标准发布流程

1. 写笔记（Obsidian 正常使用）
2. 筛选 → 把要公开的文件复制到 content/
3. 预览（可选）→ npx quartz build --serve → 浏览器 localhost:8080
4. 发布 → npx quartz sync → GitHub Actions 自动部署

避免私密内容泄露

  • 永远不要把整个 Vault 直接放进 content/
  • 在 quartz.config.ts 的 ignorePatterns 里排除私密目录（如 "private", "日记"）
  • 或者只维护一个专门的”公开”子目录，每次只从这里同步

私密内容一旦 push 就难以彻底删除（Git 历史会保留），提交前务必确认

初次部署流程（参考）

1) 准备环境

  • 确保你本机是 Node v22 + npm v10.9.2 （Quartz 4 的最低要求） Quartz

2) 初始化 Quartz 4 项目

在终端执行（官方推荐流程）： Quartz

Bashgit clone https://github.com/jackyzha0/quartz.gitcd quartznpm inpx quartz create

npx quartz create 会引导你初始化站点内容和基础配置。 Quartz

3) 把 Obsidian 的笔记放进 Quartz

Quartz 默认读取项目根目录下的 content/ 作为内容目录（你可以把 Obsidian vault 里要公开的 Markdown 复制/同步到这里）。

实用做法（选一种）：

  • 全公开 ：直接把你的 Obsidian vault 当作 content/（不推荐新手，容易把私密笔记带出去）。

  • 半公开（推荐） ：在 Obsidian 里维护完整 vault，然后 只把要发布的笔记 复制到 Quartz 的 content/。

    • 私密内容可以完全不复制
    • 或者放到你在配置里忽略的目录（例如 private/），并配合 ignorePatterns（Quartz 默认也会忽略 .obsidian） GitHub

4) 本地预览（热更新）

Bashnpx quartz build --serve

然后浏览器打开 http://localhost:8080/ 预览。 Quartz

5) 配置 baseUrl（上线前必做）

很多功能（比如 RSS / sitemap）需要你把 baseUrl 配对，否则会出问题。 Quartz

在 quartz.config.ts 里把：

  • baseUrl 改成你的域名或 GitHub Pages 地址
  • pageTitle 改成你站点标题 （quartz.config.ts 里能看到这些字段） GitHub+1

6) 部署到线上（最省事：GitHub Pages）

Quartz 官方给了 GitHub Pages 的 Actions 工作流模板： Quartz

  1. 在你的 Quartz 仓库里新建文件：quartz/.github/workflows/deploy.yml
  2. 把官方模板内容复制进去（见 Hosting 页的 GitHub Pages 部分） Quartz
  3. 到 GitHub 仓库 Settings → Pages，把 Source 选成 “GitHub Actions”。 Quartz
  4. 提交并同步（官方也推荐用这个命令）： Quartz
Bashnpx quartz sync

部署完成后，站点会在：

https://<你的用户名>.github.io/<仓库名>/ Quartz

小提示：GitHub Pages 对“带尾斜杠”的旧链接不会自动重定向，迁移时可能出现链接断裂；Quartz 官方也因此建议如果很在意兼容性，可以考虑 Cloudflare Pages。 Quartz

7) 另一个很稳的托管：Cloudflare Pages / Vercel

Quartz 官方也写了 Cloudflare Pages / Vercel 的配置要点（build command、output 目录等）。 Quartz

  • Cloudflare Pages ：build command npx quartz build，output public，生产分支一般是 v4 Quartz
  • Vercel ：同样 npx quartz build，并且需要一个 vercel.json 来启用 clean URLs（官方 Hosting 页有示例） Quartz

如果你告诉我你打算部署到 GitHub Pages / Cloudflare Pages / Vercel 里的哪一个、以及你想要的访问形式是 子路径 （username.github.io/repo）还是 独立域名 （notes.yourdomain.com），我可以按你的选项把 baseUrl 应该怎么写、以及最容易踩坑的点（路径、图片资源、双链、私密目录）给你对照表。

3 USER

你说：

把官方模板内容复制进去（见 Hosting 页的 GitHub Pages 部分 具体讲一下

4 ChatGPT 5.2

好，我把 Quartz 4 官方 GitHub Pages 模板 给你完整拆解一遍：

包含 👉 文件放哪、完整 deploy.yml 内容、每一段是干嘛的、以及常见坑。

一、文件必须放对位置

在你的 Quartz 仓库里创建：

代码.github/workflows/deploy.yml

⚠️ 注意：

  • 是 仓库根目录 下的 .github/workflows/
  • 不是 quartz/.github
  • 文件名可以叫别的，但官方示例一般叫 deploy.yml

最终结构类似：

代码your-repo/├── content/├── quartz.config.ts├── package.json└── .github/    └── workflows/        └── deploy.yml

二、官方 GitHub Pages 工作流模板（Quartz 4）

把下面完整内容复制进 deploy.yml：

YAMLname: Deploy Quartz site to GitHub Pageson:  push:    branches:      - v4   # Quartz 默认分支是 v4，如果你用 main 就改成 main  workflow_dispatch:permissions:  contents: read  pages: write  id-token: writeconcurrency:  group: "pages"  cancel-in-progress: falsejobs:  build:    runs-on: ubuntu-latest    steps:      - name: Checkout repository        uses: actions/checkout@v4      - name: Setup Node        uses: actions/setup-node@v4        with:          node-version: 22      - name: Install dependencies        run: npm ci      - name: Build Quartz        run: npx quartz build      - name: Upload artifact        uses: actions/upload-pages-artifact@v3        with:          path: public  deploy:    environment:      name: github-pages      url: ${{ steps.deployment.outputs.page_url }}    needs: build    runs-on: ubuntu-latest    name: Deploy    steps:      - name: Deploy to GitHub Pages        id: deployment        uses: actions/deploy-pages@v4

四、部署前必须做的两件事

✅ 1）修改 quartz.config.ts

TypeScriptbaseUrl: "yourusername.github.io/your-repo-name",

举例：

如果仓库叫 obsidian-notes

TypeScriptbaseUrl: "army-one-o.github.io/obsidian-notes",

⚠️ 不要带 https

⚠️ 不要加最后的 /

✅ 2）GitHub 开启 Pages

进入：

代码Repo → Settings → Pages

然后：

  • Source 选择 GitHub Actions
  • 保存

否则 workflow 会跑但页面打不开

五、第一次部署流程

Bashgit add .git commit -m "add deploy workflow"git push origin v4

然后去：

代码GitHub → Actions

等它跑完

成功后访问：

代码https://你的用户名.github.io/仓库名/

六、常见踩坑总结

❌ 页面 404

原因 99% 是：

  • baseUrl 写错
  • 分支写错
  • Pages Source 没选 GitHub Actions

❌ CSS 丢失 / 样式错乱

通常是：

  • baseUrl 少写 repo 名
  • 或多写了 /

正确格式：

代码username.github.io/repo

❌ 双链跳转 404

GitHub Pages 不会自动处理带 / 结尾的旧链接

这是 GitHub Pages 的机制问题

如果很在意 SEO，建议用 Cloudflare Pages

七、如果你想更“稳”的配置（推荐）

很多人会把触发分支改成：

YAMLbranches:  - main

然后把 quartz 主分支也改成 main

这样符合 GitHub 默认习惯

八、一句话总结部署逻辑

你 push → GitHub Actions 构建 → 输出 public → 自动部署 → Pages 发布

如果你愿意，我可以：

  • 给你画一个「Quartz + Obsidian + GitHub Pages」完整流程图
  • 或给你一套“最安全公开 Obsidian Vault 的目录策略”
  • 或教你做双仓库（私密笔记仓库 + 发布仓库）自动同步方案

你现在打算用子路径发布，还是独立域名？

5 USER

你说：

部分内容不想发布上去怎么办

6 ChatGPT 5.2

这个问题非常关键 👍 —— Quartz 4 默认会发布 content/ 里的所有 Markdown 文件 ，所以你必须主动控制哪些内容进入 content/。

下面给你 4 种方案，从「最安全」到「最方便」排序。

✅ 方案一（最推荐）：只把“公开内容”放进 content/

做法

你的 Obsidian Vault 保持完整结构：

代码MyVault/├── 私密/├── 工作/├── 日记/├── 公开/

然后：

👉 只把 公开/ 目录同步到 Quartz 的 content/

代码quartz/└── content/    ├── 公开文章1.md    ├── 公开文章2.md

优点

  • 绝对不会误传私密内容
  • 不需要复杂配置
  • 最安全

适合

想长期写公开博客的人

✅ 方案二：用 ignorePatterns 忽略目录（常用）

Quartz 允许你在 quartz.config.ts 里排除目录。

打开：

TypeScriptquartz.config.ts

找到：

TypeScriptignorePatterns: []

改成例如：

TypeScriptignorePatterns: [  "private",  "日记",  "work",]

这样这些目录不会被构建。

⚠️ 注意

路径是相对于 content/ 的。

如果你的结构是：

代码content/├── private/├── public/

写：

TypeScriptignorePatterns: ["private"]

即可。

✅ 方案三：用 Frontmatter 控制（更精细）

你可以在 Markdown 文件顶部写：

YAML---draft: true---

然后在 config 里设置：

TypeScriptignorePatterns: ["draft"]

或者用自定义插件过滤 draft（进阶玩法）。

✅ 方案四：双 Vault 架构（进阶 & 专业）

结构：

代码Obsidian 主 Vault（完整）    ↓ 手动/脚本同步Quartz 发布仓库（只放公开）

你可以：

  • 用 rsync 同步指定目录
  • 或写一个简单脚本只复制某些标签的文件
  • 或用 git subtree

优点：

  • 最安全
  • 不会误操作
  • 适合长期维护

🚨 强烈不推荐

❌ 直接把整个 Obsidian Vault 当 content

❌ 指望“到时候再删”

❌ 在 GitHub 上删私密文件（Git 记录永远存在）

🎯 最安全实践总结

场景推荐方案
偶尔发布方案一
有分类目录方案二
想精细控制单篇方案三
长期博客方案四

🔐 一个你必须知道的点

一旦 push 到 GitHub：

即使删掉文件，历史版本仍然能被看到（除非强制重写历史）。

所以：

👉 不要让私密文件进入仓库

👉 不要 push 后再想删

如果你愿意，我可以根据你现在的 Vault 结构帮你设计一个：

  • 「零风险发布结构」
  • 或一个自动同步脚本
  • 或一个“标签控制发布”的自动方案

你现在 Vault 大概是怎么分目录的？

7 USER

你说：

如何配置自定义域名

8 ChatGPT 5.2

好，我们专门讲 Quartz 4 + GitHub Pages + 自定义域名 （不是 username.github.io，而是比如 notes.yourdomain.com）。

我给你一个从 0 到可访问的完整步骤。

🎯 一、你想用哪种域名？

GitHub Pages 支持两种：

① 子域名（推荐 ✅）

代码notes.yourdomain.com

优点：

  • 配置简单
  • 不影响主站
  • 最常用

② 顶级域名

代码yourdomain.com

配置稍微复杂一点（需要 A 记录）

下面我分别讲。

🚀 二、修改 Quartz 配置（非常关键）

打开：

代码quartz.config.ts

把：

TypeScriptbaseUrl: "username.github.io/repo",

改成：

TypeScriptbaseUrl: "notes.yourdomain.com",

⚠️ 注意：

  • 不要写 https
  • 不要加 /
  • 只写纯域名

例如：

TypeScriptbaseUrl: "notes.armyoneo.com",

然后 commit 并 push。

🌐 三、GitHub 仓库设置域名

进入：

代码Repo → Settings → Pages

在 Custom domain 里填入：

代码notes.yourdomain.com

点 Save。

GitHub 会自动：

  • 在仓库里生成一个 CNAME 文件
  • 开启 HTTPS（稍等几分钟）

🧭 四、DNS 配置（最重要）

去你的域名服务商（比如 Cloudflare / 阿里云 / Namecheap）

🟢 情况 A：用子域名（推荐）

添加：

代码类型：CNAME名称：notes值：username.github.io

例如：

代码CNAMEnotes → army-one-o.github.io

⚠️ 注意：

  • 值是你的 GitHub Pages 根域名
  • 不是仓库路径
  • 不带 https

🟡 情况 B：用顶级域名

添加 4 条 A 记录：

代码185.199.108.153185.199.109.153185.199.110.153185.199.111.153

示例：

代码A @ → 185.199.108.153A @ → 185.199.109.153A @ → 185.199.110.153A @ → 185.199.111.153

GitHub 官方 IP。

🔒 五、开启 HTTPS

在：

代码Settings → Pages

勾选：

代码Enforce HTTPS

如果灰色：

  • 等 5–10 分钟
  • 或 DNS 还没生效

🧠 六、一个非常容易踩的坑

如果你之前是：

代码username.github.io/repo

现在换成自定义域名：

👉 一定要把 baseUrl 改成纯域名

否则：

  • CSS 丢失
  • 双链失效
  • 资源路径错乱

📦 七、最终结构确认

仓库根目录应该有：

代码CNAME

内容是：

代码notes.yourdomain.com

⏳ 八、多久生效？

DNS 通常：

  • 5 分钟 ~ 1 小时
  • 最慢 24 小时

可以用：

代码ping notes.yourdomain.com

检查是否解析到 github.io

🏆 九、完整流程总结

  1. 改 quartz.config.ts 的 baseUrl
  2. Push
  3. Settings → Pages → 填 Custom domain
  4. 配置 DNS
  5. 等待
  6. 开启 HTTPS

完成 🎉

如果你告诉我：

  • 你现在用的域名服务商是什么？
  • 是子域名还是主域名？
  • 仓库是不是已经能用 github.io 访问？

我可以帮你给出“精确到字段”的 DNS 填写示例。

9 USER

你说：

样式模板

10 ChatGPT 5.2

你说的“样式模板”，在 Quartz 4 里通常对应三件事：

  1. 配置层模板 （改字体/颜色/暗黑模式等，不写 CSS）
  2. CSS/SCSS 模板 （直接改 custom.scss）
  3. 布局模板 （改页面结构：左右栏、目录、图谱、搜索位置等）

下面按“从最省事到最自由”给你一套可直接套用的模板思路 + 放置位置。

1) 最省事：用 quartz.config.ts 的 theme 配置做“模板”

Quartz 4 的主题入口在 quartz.config.ts 的 theme 里，可以改 字体、颜色、以及一些基础样式变量 。DeepWiki+1

你可以把它当成“样式模板开关”，比如做三套风格：学术、极简、暖色，然后切换配置即可。

📌 位置：quartz.config.ts（theme 配置）DeepWiki+1

2) 官方推荐的“自定义样式模板文件”：quartz/styles/custom.scss

Quartz 官方明确说：大部分配色字体用配置就够；更深入的改动就写 Sass，并把你的改动放在 quartz/styles/custom.scss。quartz.jzhao.xyz+1

📌 位置：quartz/styles/custom.scss（这里就是你的“样式模板文件”）GitHub

你可以在这里做三种常用“模板化改造”：

A. 改侧边栏宽度/内容区宽度（布局体感变化最大）

思路：覆盖 CSS 变量或对应容器样式（Quartz 的 base 样式在 base.scss，自定义写在 custom.scss）。quartz.jzhao.xyz+1

B. 做“卡片风格 / 更圆角 / 更大行高”的阅读体验

写一组统一的变量/基础选择器覆盖即可。

C. 暗黑模式更“纯黑/护眼”

Quartz 自带 darkmode，并通过主题色变量切换。quartz.jzhao.xyz+1

3) 结构模板：改 quartz.layout.ts（组件拼装）

如果你说的“模板”是类似：

  • 左侧导航 + 右侧 TOC
  • 只保留单栏
  • 把图谱、最近笔记、搜索框挪位置

那就是 Layout 模板 ：在 quartz.layout.ts 里改组件组合。Quartz 文档的 Layout 页有说明，并且提到需要更深的样式变更时配合 Sass。quartz.jzhao.xyz+1

4) 想“直接套别人现成风格”？给你两个靠谱方向

Quartz 没有一个官方“主题市场”，但很多人会公开自己的 Quartz 改造仓库/日志，你可以照着抄 custom.scss 和 layout 结构：

  • 一些改造仓库会展示“换 navbar、配色、暗色侧边栏”等改法（可以当模板参考）。GitHub+1
  • 中文圈也有不少“怎么改 custom.scss、怎么换字体”的实践记录。pdcxs.github.io+1

我给你一个最快落地的建议

你如果只是想“换个好看点的皮肤”，最稳路线是：

  1. 先在 quartz.config.ts 里定好 字体 + 主色系 （当作模板 1.0）DeepWiki+1
  2. 再在 quartz/styles/custom.scss 里只做 少量覆盖 （圆角、间距、侧边栏底色）GitHub+1

你想要哪种“样式模板”？

你回我一个选项，我就直接给你一份可复制的模板代码（贴到对应文件就能用）：

  1. 极简（类似 Notion/白纸感）
  2. 学术（更适合长文、脚注、引用）
  3. 暗黑护眼（纯黑+低对比）
  4. 卡片化（更像个人主页/博客）

顺便告诉我：你站点是 单栏 还是 左右栏 布局（现在默认 Quartz 那种），我会把模板做得更贴合。

13 USER

你说：

Quartz 有推荐的主题模板吗

14 ChatGPT 5.2

简短总结一下关于 Quartz 4 是否有「官方或社区推荐的主题模板」 的情况：

✅ 1. 官方并没有像 Hugo/Hexo 那样的“主题市场”

Quartz 的官方项目本身 并不提供一组现成的主题模板 （例如 Minimal、Classic、Blog 等可切换主题包）。官方更强调：

  • 可配置的主题变量（colors、typography 等）
  • 可自定义的布局组件
  • 可覆盖的 CSS（custom.scss）

也就是说 Quartz 的主题体系是 高度可定制但不是预设模板库 。你通过配置和样式文件自己打造风格，而不是像 Hexo/WordPress 那样直接选择主题。 CSDN博客

✅ 2. 官方推荐的样式定制方式（可看作“模板源”）

虽然没有主题市场，但 Quartz 提供两个核心地方让你打造自己的“主题模板”：

🎨 主题变量（theme 配置）

在 quartz.config.ts 的 theme 部分，你可以配置：

TypeScripttheme: {  colors: { /* 主色/暗黑模式 配色 */ },  typography: { /* 标题／正文字体配置 */ },}

这基本就是官方支持的“主题引擎”变量层，你可以把它当成“轻量主题模板”。 CSDN博客

✍ 自定义样式文件：quartz/styles/custom.scss

官方鼓励用户 通过自定义 SCSS 文件来覆盖 Quartz 默认样式 ：

  • 改字体
  • 改侧边栏风格
  • 卡片化样式
  • 不同的按钮、间距、颜色
  • 自定义暗黑模式配色

这是 Quartz 真正实现“主题”的地方（官方示例项目也默认有这个文件）。 CSDN博客

🟡 3. 社区/第三方“主题集”例子

虽然官方没有主题市场，但社区有一些第三方的主题集合项目，例如：

quartz-themes（第三方主题集）

这是一个据说专门为 Quartz 提供多种主题风格的开源项目（通过 Sass + 脚本安装到 Quartz 里），支持自动安装、亮/暗色模式等。 CSDN博客

这类项目能让你：

  • 快速切换视觉风格
  • 拥有预置的色彩/排版体系
  • 可通过脚本自动应用

⚠️ 注意：这种第三方主题并不是 Quartz 官方维护，但给你一个“主题包”的体验。

🧠 4. 实际推荐策略

因为 Quartz 核心是可定制而不是主题化，最推荐的做法是：

✅ 使用配置 + SCSS 自建一套主题

你可以：

  1. 在 quartz.config.ts 里设主色、字体
  2. 在 quartz/styles/custom.scss 写样式覆盖
  3. 把这些文件当成你的“主题模板”
  4. 在不同项目里复用这套主题代码

这种方式比简单套主题更灵活，也更“Quartz 风”。 CSDN博客

🏷️ 5. 典型样式方向 & 模板思路

如果你想快速成型，这里是常见的“主题模板风格方向”：

🌿 ① 极简 / 阅读优先

  • 少色背景
  • 大行距、宽内容区
  • 隐藏多余 UI

✨ 适合个人笔记/长文发布

🎓 ② 学术 / 引用风

  • Serif 字体标题
  • 清晰侧边 TOC
  • 更明显引用样式

✨ 适合论文/知识库

🖤 ③ 暗黑 / 夜间模式优先

  • 强对比暗背景
  • 柔和高亮色
  • 隐性边框

✨ 适合夜间阅读

🧱 ④ 博客 / 卡片化风格

  • 卡片外观文章摘要
  • 动画悬停效果
  • 自定义按钮样式

✨ 适合博客/作品集

🧩 6. 想要现成代码模板吗？

我可以为你写出 可直接复制到 quartz/config + custom.scss 的完整主题模板 —— 只需要你回答下面两个问题：

  1. 你偏好哪种视觉风格（极简 / 学术 / 暗黑 / 博客卡片 / 其他）？
  2. 你主要用途是什么（博客 / 数字花园 / 知识库）？

回复这两个，我给你现成的“主题模板代码”。

关系图谱