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` 排除

quartz-wiki

SKILL.mdquartz-skill/SKILL.md