quartz-wiki

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: 初始化

# 方式1：git clone（需要翻墙时用 --depth 1 加速）
git clone --depth 1 --branch v4 https://github.com/jackyzha0/quartz.git
cd quartz
npm i

# 方式2：如果 clone 不可用，手动下载 v4 分支 zip 解压

前提条件：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   # 不推荐，会清空 public
# 或构建后用 python 起服务器：
python -m http.server 8080 -d public

验证清单：

• 首页正常显示
• 侧边栏导航可用
• [[wikilinks]] 双向链接跳转正确
• 关系图谱（Global Graph）弹出正常
• 全文搜索可用
• 图片正常加载
• 暗色模式切换正常

Phase 5: 部署

详见 quartz-deployment.md。

配置要点

关键配置项（quartz.config.ts）

{
  configuration: {
    pageTitle: "你的Wiki名称",       // 站点标题
    locale: "zh-CN",                  // 中文支持
    baseUrl: "https://your-domain.com", // 不能为空！否则 404 页面构建崩溃
    ignorePatterns: ["raw", "private", "templates"],  // 排除目录
  },
  plugins: {
    transformers: [
      Plugin.ObsidianFlavoredMarkdown(),  // 支持 [[wikilinks]]
      Plugin.GitHubFlavoredMarkdown(),
      Plugin.TableOfContents(),            // 自动生成目录
      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
      // Plugin.Latex(),                   // 如需数学公式
    ],
  },
}

Frontmatter 规范（给内容文件的）

---
title: "页面标题"          # 必填，显示在页面和侧边栏
date: 2026-04-24          # 用于排序
tags:                     # 可选，用于标签页
  - wiki
  - lego
---

禁止使用的 frontmatter 字段（与 Quartz 冲突）：

• aliases: → 用 also_known_as: 替代
• slug: → 用文件名控制 URL
• publish: → 用 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 排除