Quartz：把 Markdown 笔记变成可搜索、可漫游的数字花园

你已经有一堆 Markdown 笔记。问题不是写不出来，而是它们永远躺在本地文件夹里：搜索靠编辑器，引用靠记忆，分享靠复制粘贴。

把这些内容搬到传统博客也不对。博客假设文章是一条时间线，数字花园假设知识是一张网。Quartz 做的就是后者：把 Markdown 笔记发布成一个可以搜索、跳转、回看关系的静态网站。

Quartz 是什么

Quartz 是一个开源静态站点生成器，专门用于发布数字花园、个人知识库和 Obsidian 风格笔记。官方描述很直接：它把 Markdown 内容变成完整可用的网站。

它不是另一个通用博客框架。Quartz 的默认能力围绕”笔记之间的关系”设计：

能力	解决什么问题
Wikilinks	用 [[Note Name]] 连接笔记
Backlinks	自动显示哪些页面引用了当前页面
Graph View	把知识库关系渲染成图
Full-text Search	在站内直接搜索内容
Popover Preview	鼠标悬停就能预览链接页面
Obsidian Compatibility	保留 Obsidian 用户的写作习惯
LaTeX / Mermaid / Syntax Highlighting	支持技术笔记常见格式

截至 2026 年 5 月，Quartz v4 文档站显示版本为 v4.5.2；GitHub 仓库 jackyzha0/quartz 约有 12.2k stars 和 3.8k forks。它已经不是一个实验脚本，而是一个被大量笔记作者、学生、开发者和教师使用的发布工具。

它强在哪里

Quartz 的优势不是”能生成静态页面”。这个 Hugo、Astro、Next.js 都能做。它强在默认就把知识库需要的东西装好了。

它保留 Markdown 的低摩擦。 你继续写 Markdown，不需要把每篇笔记改造成 CMS 条目。内容仍然是普通文件，版本控制、搜索、AI 处理都方便。

它理解双链。 普通静态站点把链接当导航，Quartz 把链接当知识结构。Wikilinks、backlinks、graph view 让读者能沿着概念走，而不是只按时间或目录阅读。

它适合渐进式发布。 数字花园不是”写完再发”。你可以发布半成品笔记、持续补链接、改结构。Quartz 的页面、标签、文件夹和关系图会跟着内容演化。

它足够快。 静态站点没有数据库请求，页面加载快，部署成本低。官方也强调快速页面加载和小 bundle。

适合哪些场景

个人知识库公开化。 如果你已经用 Obsidian、Logseq 或纯 Markdown 写笔记，Quartz 是把本地知识库发布到网页上的直接路径。

研究笔记和课程资料。 论文阅读、课程讲义、实验记录天然是网状结构。Graph、backlinks 和悬浮预览能让读者在概念之间来回跳，不必依赖线性目录。

产品或技术团队 wiki。 小团队不一定需要重型知识库系统。把 Markdown 放进 Git，用 Quartz 生成站点，审阅、部署、回滚都走工程流程。

AI 资料库。 如果你在整理 prompts、模型行为、工具链经验，Quartz 的链接结构很适合把”概念、案例、失败模式、代码片段”互相连接。

不适合的地方

Quartz 不是万能内容平台。

不要把它当 WordPress。 如果你需要后台编辑器、多人权限、评论审核、付费墙、复杂表单，Quartz 不是主战场。它更像”Git 管理的公开知识库”。

不要期待零配置品牌站。 Quartz 默认主题已经够用，但深度品牌化仍要改配置、布局和组件。它比 SaaS 建站工具自由，也比它们更需要工程介入。

大型私密知识库要谨慎。 Quartz 支持 private pages 和 ignore patterns，但静态站点的核心模型是发布。敏感内容要在内容源头隔离，而不是指望构建后再补救。

文件名和链接策略要早定。 数字花园最怕后期大规模改 slug。短链接、目录结构、标签规范最好在前 20 篇笔记里就确定。

Quartz 最适合的不是”我要写博客”，而是”我已经有一张知识网，想把它公开给别人走进去”。

安装

Quartz 当前要求 Node v22 和 npm v10.9.2 以上。官方快速开始如下：

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

create 命令会引导你初始化内容目录。完成后，你可以开始写 Markdown、改配置、预览和部署。

快速上手

Quartz 项目里最常碰的文件是这几个：

文件	用途
content/	放 Markdown 笔记
quartz.config.ts	配置站点标题、主题、插件、解析规则
quartz.layout.ts	配置页面布局和组件位置
quartz/components/	自定义组件
quartz/plugins/	自定义解析、过滤和输出逻辑

创建一篇笔记：

---
title: Context Engineering
tags:
  - ai
  - prompt-engineering
---

Context engineering is not about stuffing more text into a prompt.
It is about deciding what the model needs to see right now.

Related: [[RAG]], [[Function Calling]], [[Agent Memory]]

这篇笔记发布后，Quartz 会把 wikilinks 解析成站内链接。被引用的页面会在 backlinks 区域显示反向引用，关系图也会出现连接。

本地构建和预览通常走 Quartz CLI：

npx quartz build --serve

如果只想生成静态文件用于部署：

npx quartz build

配置一个更像知识库的站点

Quartz 的默认配置已经启用一组常用 transformer、filter 和 emitter。你会在 quartz.config.ts 里看到类似结构：

const config = {
  configuration: {
    pageTitle: "My Digital Garden",
    enableSPA: true,
    enablePopovers: true,
    locale: "en-US",
    ignorePatterns: ["private", "templates", ".obsidian"],
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.ObsidianFlavoredMarkdown(),
      Plugin.GitHubFlavoredMarkdown(),
      Plugin.TableOfContents(),
      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
      Plugin.Latex({ renderEngine: "katex" }),
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.ContentPage(),
      Plugin.FolderPage(),
      Plugin.TagPage(),
      Plugin.ContentIndex({ enableSiteMap: true, enableRSS: true }),
    ],
  },
}

这套配置的关键点是：先把 Markdown 解析成 Quartz 能理解的内容图，再过滤不该发布的内容，最后输出页面、目录页、标签页、RSS 和 sitemap。

实践示例：把 AI 笔记发布成数字花园

假设你有一个 AI 学习目录：

content/
  index.md
  rag.md
  function-calling.md
  agent-memory.md
  prompt-injection.md

你可以在 index.md 写一个入口：

---
title: AI Systems Notes
tags:
  - ai
---

Start here:

- [[RAG]] for retrieval-heavy systems
- [[Function Calling]] for tool execution
- [[Agent Memory]] for long-running workflows
- [[Prompt Injection]] for security boundaries

然后在每篇笔记里互相引用：

---
title: Agent Memory
tags:
  - agents
  - memory
---

Agent memory is useful when a task spans multiple sessions.
It becomes risky when the system stores unverified user input.

Security boundary: [[Prompt Injection]]
Retrieval pattern: [[RAG]]

这时 Quartz 的价值就出来了：读者不只是看到一篇文章，而是能沿着”记忆 → 检索 → 安全边界”走完整个知识网络。

导航应该怎么设计

Quartz 站点最容易犯的错，是把它设计成传统博客：顶部放 Home、Blog、About，左侧再堆一个完整目录树。这样能用，但浪费了 Quartz。

更好的做法是把导航拆成三层：入口导航、语义导航、局部导航。

层级	承担什么职责	适合放什么
入口导航	告诉读者这个站点有哪些大区域	Notes、Projects、Topics、About
语义导航	让读者沿着概念移动	Wikilinks、backlinks、tags、graph view
局部导航	帮读者理解当前页面结构	Table of contents、folder page、related notes

顶部导航不要太重。它只负责把读者带进正确区域，不负责解释整个知识库。真正的探索应该交给链接、反向链接、标签和关系图。

如果你在发布 AI 知识库，可以这样设计：

顶部导航	作用
Start Here	给第一次访问的人一个入口
Concepts	放 RAG、agents、prompting、evaluation 等核心概念
Patterns	放可复用方案，如 retrieval pipeline、tool use、memory design
Notes	放未完全打磨但值得公开的研究笔记
About	说明作者、更新节奏和内容边界

然后把每篇笔记内部写成一张网，而不是一篇孤岛文章：

---
title: Agent Memory
tags:
  - agents
  - memory
status: working-note
---

Agent memory matters when a task spans multiple sessions.

Use it with [[RAG]] when the agent needs external context.
Treat [[Prompt Injection]] as the security boundary.
Compare with [[Context Window]] before adding persistence.

这个结构的重点不是”导航栏更漂亮”，而是降低读者的下一步成本。读者看完一页，应该马上知道还能去哪里：继续读概念、看模式、回到主题页，或沿着 backlinks 找到争议点。

一个可执行的导航原则：

• 顶部导航不超过 5 项
• 每篇核心笔记至少有 3 个 outgoing links
• 每个 tag 页面都应该像专题页，而不是标签垃圾桶
• Start Here 页面只服务新读者，不承担全部目录功能
• Graph view 是探索辅助，不是主导航

Quartz 的导航设计，核心不是”把所有入口展示出来”，而是让读者在每一步都有一个合理的下一跳。

常见坑

把目录当导航树设计。 数字花园的主导航不该承担全部结构。目录负责粗分类，链接负责语义关系。把所有东西塞进目录，Quartz 的优势会被削弱。

页面太像博客。 如果每篇文章都只有时间、标题、正文，没有 outgoing links 和 backlinks，Quartz 只是一个复杂版博客引擎。

忽略未完成内容标记。 半成品可以发布，但最好在 frontmatter、标签或正文里标清状态。否则读者会把草稿当结论。

照搬 Obsidian 插件习惯。 Quartz 兼容很多 Obsidian 写法，但不是完整 Obsidian 运行时。依赖本地插件生成的动态内容，发布后可能不会按预期工作。

结尾

Quartz 的核心价值不是把 Markdown 变成网页，而是把一堆孤立笔记变成可以被探索的知识网络。

如果你的内容天然靠链接组织，别先搭博客。先让 Quartz 把这张网跑起来。

GitHub: https://github.com/jackyzha0/quartz
Docs: https://quartz.jzhao.xyz/