| name | quartz-wiki |
| description | Set up and deploy Quartz v4 static site for markdown wikis. Use when the user says "部署wiki", "quartz", wants to publish wiki as a website, deploy to Cloudflare Pages/Vercel/GitHub Pages, configure Quartz, fix Quartz build errors, or troubleshoot Quartz issues. Covers initialization, configuration, YAML frontmatter fixes, wikilink support, content management, and deployment. |
Quartz Wiki — 静态站点部署器
将已有的 Markdown Wiki 部署为 Quartz v4 静态网站，支持双向链接、关系图谱、全文搜索。
工作流
当用户说「部署 wiki」「quartz」「发布网站」时：
Phase 1: 初始化
git clone --depth 1 --branch v4 https://github.com/jackyzha0/quartz.git
cd quartz
npm i
前提条件：Node.js v22+, npm v10.9.2+
Phase 2: 内容接入
将已有 wiki 内容放入 quartz/content/ 目录。
关键决策：
- Symlink（开发用）：
ln -s ../wiki content — 但 Windows 上可能缓存旧内容，出问题时换 copy
- Copy（部署用）：
cp -r ../wiki content — 每次构建前同步
- Git 管理（生产推荐）：content 目录纳入 git，CI/CD 自动同步
必须排除的目录：在 quartz.config.ts 的 ignorePatterns 中添加 raw、private、templates 等。
详见 quartz-setup.md 的完整配置指南。
Phase 3: Frontmatter 修复
Quartz 对 YAML frontmatter 有严格要求。部署前必须检查并修复以下问题：
| 问题 | 症状 | 修复 |
|---|
aliases: 字段冲突 | 构建报错 "ENOTEMPTY" / alias emitter 崩溃 | 重命名为 also_known_as: |
YAML # 注释 | 构建报错 "missed comma" | 去掉 # 或用引号包裹 "#6539" |
内联列表 [a, b] | 偶发 YAML 解析失败 | 改为标准 - a\n- b 格式 |
| 空值字段 | 解析异常 | 设为空字符串或删除 |
详见 quartz-troubleshooting.md 的完整修复脚本。
Phase 4: 构建与验证
rm -rf .quartz-cache public
npx quartz build
npx quartz build --serve
python -m http.server 8080 -d public
验证清单：
Phase 5: 部署
详见 quartz-deployment.md。
配置要点
关键配置项（quartz.config.ts）
{
configuration: {
pageTitle: "你的Wiki名称",
locale: "zh-CN",
baseUrl: "https://your-domain.com",
ignorePatterns: ["raw", "private", "templates"],
},
plugins: {
transformers: [
Plugin.ObsidianFlavoredMarkdown(),
Plugin.GitHubFlavoredMarkdown(),
Plugin.TableOfContents(),
Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
],
},
}
Frontmatter 规范（给内容文件的）
---
title: "页面标题"
date: 2026-04-24
tags:
- wiki
- lego
---
禁止使用的 frontmatter 字段（与 Quartz 冲突）：
aliases: → 用 also_known_as: 替代slug: → 用文件名控制 URLpublish: → 用 draft: true 控制草稿
常见问题速查
| 问题 | 解决方案 |
|---|
npx create-quartz 404 | 这个包不存在，用 git clone |
git clone 超时 | 用 --depth 1 浅克隆 |
| 构建报错 "missed comma" | YAML # 注释问题，修复 frontmatter |
| 构建报错 "ENOTEMPTY" | aliases: 字段冲突，改名为 also_known_as: |
| 构建报错 "Invalid URL" | baseUrl 为空，设置有效 URL |
| 内容没更新 | 清理 .quartz-cache，Windows symlink 换 copy |
| 图片不显示 | 检查图片 URL 是否可访问，外链图片无需额外配置 |
| 中文乱码 | 设置 locale: "zh-CN"，确保 md 文件是 UTF-8 编码 |
| 构建产物太大 | 检查是否有大文件被意外包含，用 ignorePatterns 排除 |
