Jasonmumiao

Quartz 配置过程

6分钟阅读

Quartz 配置过程

这篇笔记记录本 vault 的公开发布方式。内部账号、仓库地址、本地路径和部署标识已脱敏。

基本信息

本地 vault 路径：已脱敏
GitHub 仓库：Private repository，地址不公开
仓库可见性：Private
Quartz 版本：v5
Node 要求：22+
仓库 Node 版本文件：.node-version = v22.16.0
构建输出目录：public
默认内容目录：content
公开站点：https://obsidian-jasonmumiao-quartz.pages.dev

当前 Quartz 的 baseUrl 先设置为：

obsidian-jasonmumiao-quartz.pages.dev

如果之后在 Cloudflare Pages 绑定自定义子域名，例如 notes.example.com，需要修改根目录的 quartz.config.yaml：

configuration:
  baseUrl: notes.example.com

注意不要写 https://，也不要在末尾加 /。

目录结构

vault-root/
  .obsidian/          # Obsidian 本地配置
  content/            # Quartz 发布内容
    index.md          # 网站首页
    attachments/      # 图片和附件
  private/            # 本地私有内容，已忽略
  quartz/             # Quartz 构建程序
  quartz.config.yaml  # Quartz 站点配置
  package.json        # Node/Quartz 构建脚本
  public/             # 构建产物，已忽略

Obsidian 设置

本 vault 的 .obsidian/app.json 已配置：

新建笔记目录：content
附件目录：content/attachments
自动更新链接：开启
隐藏工程目录：quartz、node_modules、public、.github 等

因此后续在 Obsidian 里新建普通笔记时，默认会进入 content/，并会被 Quartz 发布。

Quartz 设置

根目录的 quartz.config.yaml 已做这些调整：

pageTitle：Jasonmumiao
locale：zh-CN
analytics：null
fontOrigin：local
baseUrl：obsidian-jasonmumiao-quartz.pages.dev
explicit-publish：关闭
remove-draft：关闭

explicit-publish 关闭表示不需要给每篇笔记写 publish: true。只要 Markdown 文件在 content/ 下，Quartz 就会发布。

remove-draft 关闭表示即使笔记里有 draft: true，也不会被 Quartz 自动过滤。这符合“发布这个新 vault 的所有笔记”的目标。

本地预览

在 vault 根目录执行：

npm install
npm run quartz -- plugin install --from-config
npm run quartz -- build --serve

本地访问：

http://localhost:8080

只构建不启动预览服务器：

npm run quartz -- build

GitHub 推送

本地仓库 remote：

git remote add origin <private-repository-url>

首次推送：

git push -u origin main

.obsidian/plugins/ 已被 .gitignore 忽略，避免把本地插件文件、同步插件数据或 token 类配置推到 GitHub。Obsidian 的基础 vault 设置会保留，但插件本体需要在新设备上重新安装。

后续日常更新：

git add .
git commit -m "Update notes"
git push

如果使用 Obsidian Git 插件，可以用命令：

Git: Commit-and-sync

Cloudflare Pages 配置

当前状态

Wrangler 已登录 Cloudflare：

Cloudflare Account ID: 已脱敏
Pages project: obsidian-jasonmumiao-quartz
Pages URL: https://obsidian-jasonmumiao-quartz.pages.dev

GitHub App 授权完成后，已通过 Cloudflare API 创建 GitHub 集成 Pages 项目：

Project name: obsidian-jasonmumiao-quartz
Production branch: main
Git provider: GitHub
Repository: Private GitHub repository，名称不公开
Build command: npm run quartz -- plugin install --from-config && npm run quartz -- build
Build output directory: public

现在每次 main 分支有新的 push，Cloudflare Pages 都会自动拉取仓库、安装依赖、运行 Quartz 构建并发布到 pages.dev 域名。

首次生产部署已成功：

Deployment ID: 已脱敏
Trigger: github:push
Commit: 已脱敏
Status: success
Verified URL: https://obsidian-jasonmumiao-quartz.pages.dev

已用 HTTP 请求和浏览器渲染检查确认首页可访问，且页面包含 Jasonmumiao 和 欢迎。

Dashboard 手动创建参数

在 Cloudflare Dashboard 创建 Pages 项目：

Pages -> Create a project -> Connect to Git

选择仓库：

<private-repository>

推荐填写：

Project name: obsidian-jasonmumiao-quartz
Production branch: main
Framework preset: None
Build command: npm run quartz -- plugin install --from-config && npm run quartz -- build
Build output directory: public
Root directory: /

仓库根目录已包含 .node-version：

v22.16.0

Cloudflare Pages 通常会读取这个文件。如果 Cloudflare Pages 没有自动使用 Node 22+，在 Pages 项目的环境变量里添加：

NODE_VERSION=22.16.0

Pages 项目和自定义域名可以在 Cloudflare Dashboard 中管理；涉及账号、仓库和授权的内部信息不写入公开笔记。

构建成功后，默认地址通常是：

https://obsidian-jasonmumiao-quartz.pages.dev

绑定自定义子域名

Cloudflare Pages 项目中进入：

Custom domains -> Set up a custom domain

填入你的子域名，例如：

notes.example.com

绑定成功后，同步修改 quartz.config.yaml 的 baseUrl：

configuration:
  baseUrl: notes.example.com

然后提交并推送，Cloudflare Pages 会自动重新构建。

日常工作流

1. 在 Obsidian 写笔记
2. 笔记和附件保存在 content/
3. Git commit/push 到 GitHub private repo
4. Cloudflare Pages 自动检测 main 分支更新
5. 自动运行 Quartz 构建
6. 网站更新

注意事项

  • content/ 下的所有笔记都会作为公开站点内容发布。
  • 仅将适合公开阅读的内容放入 content/。
  • public/ 是构建产物，不需要提交。
  • 图片建议使用本地附件并放在 content/attachments/，这样网站会把图片作为静态资源一起发布。

关系图谱