Quartz

🎯 为什么需要它

你有一个 Obsidian 知识库，里面积累了大量笔记、双向链接和图谱关系。你想把这些笔记发布到网上，让别人也能浏览你的数字花园（Digital Garden），但又不想手动维护一个网站。

Quartz 就是为这个场景而生的。它是一套基于 TypeScript 的静态站点生成器，专门将 Markdown 内容（尤其是 Obsidian 风格的笔记）转化为功能完备的网站，具备双向链接、图谱视图、全文搜索等数字花园核心特性。

一句话定位

把你的 Obsidian 知识库变成一个可在线访问的数字花园，零后端、免费托管。

它解决的核心痛点

• Obsidian Publish 太贵 — 每月 $8/用户，Quartz 完全免费
• 手动建站太累 — 传统 SSG（Hugo/Astro）需要自己实现双向链接、图谱、backlinks
• 知识需要流动 — 笔记不该锁在本地，数字花园理念鼓励公开分享和持续迭代

✅ 核心优势

⚡ 性能表现

Quartz v4 使用 esbuild 作为构建工具，构建速度极快。

构建性能

• 构建工具：esbuild（Go 编写的超快 JS bundler）
• 增量构建：内容修改时只重建变更部分，大型知识库（1000+ 笔记）也能秒级构建
• 热重载：配置修改和内容修改都支持 HMR，开发体验流畅

运行时性能

• SPA 路由：首次加载后，页面切换通过客户端路由实现，无需整页刷新
• 预加载：鼠标悬停链接时自动预加载目标页面
• Bundle 体积：TypeScript 85.2% + SCSS 8.3%，输出为纯静态 HTML/CSS/JS，体积小
• 零服务端依赖：纯静态文件，CDN 友好，TTFB 极低

🚀 快速上手

前置要求

• Node.js >= v22
• npm >= v10.9.2
• Git

Step 1：克隆并初始化

git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create

npx quartz create 会引导你选择：从现有 Obsidian vault 导入内容，或创建空白项目。

Step 2：放入你的内容

将你的 Markdown 笔记放入 content/ 目录。Quartz 会自动识别 wikilinks、frontmatter、标签等 Obsidian 语法。

content/
  ├── index.md          # 首页
  ├── notes/
  │   ├── my-note.md    # 你的笔记
  │   └── another.md
  └── tags.md           # 标签页

Step 3：本地预览

npx quartz build --serve

访问 http://localhost:8080 即可预览。修改内容会自动热重载。

Step 4：配置你的站点

编辑 quartz.config.ts 自定义站点信息：

const config: QuartzConfig = {
  configuration: {
    pageTitle: "My Digital Garden",
    enableSPA: true,
    enablePopovers: true,
    baseUrl: "yoursite.com",
    // ... 更多配置
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.Latex({ renderEngine: "katex" }),
      // ...
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.AliasRedirects(),
      Plugin.ComponentResources(),
      // ...
    ],
  },
}

Step 5：部署上线

npx quartz build

构建产物在 public/ 目录，推送到 GitHub 后可配置 GitHub Pages / Cloudflare Pages / Vercel 自动部署。

典型部署流程（GitHub Pages）

1. Fork Quartz 仓库到你的 GitHub 账号
2. 在 content/ 目录放入你的笔记
3. 推送到 main 分支
4. 在仓库 Settings → Pages 中启用 GitHub Actions 部署
5. 每次 push 自动构建并发布

📦 适用场景

✅ 最佳使用场景

⚠️ 不太适合的场景

⚠️ 已知坑

🆚 竞品对比

选型建议

• 选 Quartz：你用 Obsidian，想免费发布数字花园，需要开箱即用的双向链接/图谱/搜索
• 选 Hugo：你追求极致构建速度，内容量巨大（万级页面），不介意自己配置数字花园功能
• 选 Astro：你需要高度定制的网站，团队有前端开发能力，数字花园只是其中一个需求
• 选 Obsidian Publish：你不想折腾任何技术细节，愿意付费换取零维护体验

🌍 生态社区

项目数据

社区资源

• 官方文档：quartz.jzhao.xyz（也有仓库内 docs/ 目录可离线阅读）
• Discord 社区：活跃的用户交流群，问题响应较快
• Showcase：官方文档有 showcase 页面，展示大量真实用户站点
• 视频教程：Nicole van der Hoeven 等 YouTuber 有详细的视频上手指南

维护状态评估

虽然最新 Release 停留在 2023 年 8 月，但主分支持续有 commit，Issues 仍在响应。项目由作者 Jacky Zhao 个人维护，社区贡献活跃。属于「个人项目但社区健康」的状态。

💡 引入评估

值不值得引入？

引入决策树

1. 你用 Obsidian 吗？→ 是 → 继续
2. 你想免费发布吗？→ 是 → 继续
3. 你需要双向链接/图谱/搜索吗？→ 是 → 选 Quartz
4. 你愿意付费省事吗？→ 是 → 考虑 Obsidian Publish
5. 你需要极致构建速度（万级页面）？→ 是 → 考虑 Hugo

🔗 相关链接

标签

📝 个人备注