Quartz:把 Markdown 笔记变成静态网站的开源工具

Quartz 是一个把 Markdown 笔记变成网站的静态站点生成器，对开发者来说，它解决了"笔记写了不少、但没地方展示"的问题。这个项目在 GitHub 上有 13452 个 star，协议是 MIT，你可以免费拿来用，甚至改造成自己的博客或数字花园。

适合谁

笔记重度用户：平时用 Obsidian、Typora 这类工具写 Markdown，想把这些笔记整理成一个公开网站，Quartz 可以直接吃你的 Markdown 文件，不用重新排版。

想折腾自建博客的开发者：不想用 WordPress 那种重方案，也不想被托管平台绑定，Quartz 生成的是纯静态页面，部署到任何支持静态文件的服务器就行。

数字花园爱好者：Quartz 官方定位就是"digital garden"，它把笔记间的双链、反向链接都保留下来，适合做知识库型网站，而不是传统的时间线博客。

能解决什么问题

笔记一键变网站：你本地维护一个 Markdown 文件夹，Quartz 会把它渲染成完整的网站结构，包括目录、搜索、标签页。不需要手动写 HTML 页面。

保留笔记的双链关系：Obsidian 里写的 [[双链]] 在 Quartz 生成的网站上能正常点击跳转，这对知识库型网站很关键，传统静态生成器大多不支持这个。

部署成本低：生成的是纯静态文件，可以扔到 GitHub Pages、Netlify 或者任何 Nginx 服务器上，不需要数据库和后端服务。

怎么开始用

Quartz v5 的安装方式很直接，需要 Node.js 环境。先克隆仓库：

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

本地预览：

npx quartz build --serve

构建生产版本：

npx quartz build

官方文档在 https://quartz.jzhao.xyz/ ，里面有完整的配置说明。注意 Quartz 依赖 Node.js 环境，需要提前装好。

优点和坑

优点：

• 配置相对简单，官方文档写得清楚，跟着走基本能跑通
• 对 Markdown 语法支持完整，包括代码块、数学公式、双链这些
• 社区活跃，Discord 上有官方社区（https://discord.gg/cRFFHYye7t），遇到问题有人答

坑：

• Node.js 版本要求：Quartz v5 对 Node 版本有要求，如果本机 Node 版本太旧，npm i 或构建会报错，需要先升级 Node
• 主题定制有门槛：默认主题能用，但想改样式得懂一点 SCSS，不会前端的话只能停留在默认外观
• 插件机制需要学习：Quartz 的功能靠插件扩展，配置插件要读文档，不是开箱即点即用
• 构建速度一般：笔记数量多的时候，全量构建会变慢，官方没有给出具体数据，但大仓库下等待时间明显

适合你吗

适合：你已经在用 Markdown 记笔记、想低成本搞一个个人知识库网站、愿意花半小时读文档配环境。Quartz 的 MIT 协议意味着你可以放心商用或二次开发。

不适合：完全不想碰命令行、只想点点鼠标建站的用户，Quartz 不适合你，建议用托管平台；需要多用户协作或后台管理的网站，Quartz 是纯静态方案，没有这些功能。

一句话总结：Quartz 适合愿意折腾的开发者，把笔记变成网站这件事它做得挺干净，但前提是你得能接受命令行和配置文件。

---

常见问题

Quartz 这个工具有中文名或中文翻译吗？

Quartz 是一个英文项目名，没有官方中文翻译。它是一个开源工具，主要功能是把你的 Markdown 笔记文件一键生成为静态网站，常被称作“数字花园”或“静态站点生成器”。

Quartz 是免费的吗？

是的，Quartz 完全免费。它是一个在 GitHub 上开源的静态站点生成器，采用 MIT 协议，这意味着你可以免费使用、修改甚至用于商业项目，无需付费。

Quartz 怎么安装和开始使用？

安装 Quartz 需要 Node.js 环境。首先克隆项目仓库：git clone https://github.com/jackyzha0/quartz.git，然后进入目录运行 npm i 安装依赖。本地预览使用命令 npx quartz build --serve。

Quartz 和 WordPress 这类博客平台有什么主要区别？

Quartz 是静态站点生成器，它把你的 Markdown 文件生成纯静态网页，无需数据库和后台服务，部署简单成本低。而 WordPress 是动态内容管理系统，功能更重，需要数据库和 PHP 环境，也更易被托管平台绑定。

使用 Quartz 有什么需要注意的缺点或坑？

主要有几点：对 Node.js 版本有要求，版本太旧会报错；自定义主题需要懂 SCSS 前端知识；功能通过插件扩展，需要学习配置；当笔记数量非常多时，全量构建速度会变慢，需要等待。

相关工具推荐

• Pelican：同为静态网站生成器，用Python将Markdown发布为博客
• TinaCMS：另一个基于Git仓库、支持Markdown的可视化无头CMS
• Open-LLM-VTuber：了解其他有趣的开源项目，如结合大语言模型的虚拟主播