| name | quartz-wiki |
| description | 把 ai-wiki/wiki/ 下的 Markdown 知识库部署为 Quartz v4 静态网站。当用户说「部署 wiki」「发布网站」「quartz 构建」时触发。支持双向链接、全局关系图谱、全文搜索、暗色模式。 |
Quartz Wiki — 静态站部署器
把 ai-wiki/wiki/ 下整理好的 Markdown 知识库，输出为带双向链接、关系图谱、全文搜索的 Quartz v4 网站。
前置条件
- Node.js v22+
- npm v10.9+
ai-wiki/wiki/ 已通过 llm-wiki-skill 整理过，frontmatter 干净
五阶段流程
Phase 1: 初始化 Quartz（首次）
cd quartz
git clone --depth 1 --branch v4 https://github.com/jackyzha0/quartz.git .
npm i
npx create-quartz 不存在，必须 git clone v4 分支。
Phase 2: 内容接入
把 ai-wiki/wiki/ 接入 quartz/content/：
| 方式 | 适用 | 说明 |
|---|
| symlink | 开发 | ln -s ../../ai-wiki/wiki content，改一份生效。Windows 缓存有坑 |
| copy | 部署 | cp -r ../ai-wiki/wiki content，每次构建前同步 |
| git submodule / CI 拉取 | 生产 | 推荐 |
quartz.config.ts 必须排除：raw、templates、private、.obsidian。
Phase 3: Frontmatter 修复（关键）
Quartz YAML 解析严格，部署前先扫一遍：
| 问题 | 症状 | 修复 |
|---|
aliases: 字段 | 构建报错 ENOTEMPTY | 改名为 also_known_as: |
YAML # 注释 | "missed comma" | 去掉 # 或加引号 "#6539" |
内联列表 [a, b] | 偶发解析失败 | 改成 - a\n- b |
| 空值字段 | 解析异常 | 删除或设空字符串 |
Phase 4: 构建与本地预览
rm -rf .quartz-cache public
npm run quartz -- build
python -m http.server 8080 -d public
验证清单：
Phase 5: 远程部署（nginx VPS）
bash .agents/skills/quartz-wiki/scripts/deploy.sh
可选参数：--skip-build（仅 rsync 已有 public/）、--dry-run（rsync 干跑）。
环境变量覆盖：DEPLOY_HOST / DEPLOY_PATH / DEPLOY_DOMAIN。
完整流程（含服务器侧 nginx 配置、certbot HTTPS、多设备维护、排错）见
references/deployment-nginx-vps.md。
部署前置检查：
其他平台: Cloudflare Pages / Vercel / GitHub Pages 待补 references/deployment-<platform>.md。
quartz.config.ts 关键配置
{
configuration: {
pageTitle: process.env.SITE_TITLE ?? "LLM Wiki",
locale: process.env.SITE_LOCALE ?? "zh-CN",
baseUrl: process.env.SITE_BASE_URL,
ignorePatterns: ["raw", "private", "templates", ".obsidian"],
},
plugins: {
transformers: [
Plugin.ObsidianFlavoredMarkdown(),
Plugin.GitHubFlavoredMarkdown(),
Plugin.TableOfContents(),
Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
],
},
}
内容文件 frontmatter 规范
---
title: "页面标题"
date: 2026-05-05
tags:
- wiki
- concept
---
禁用字段（与 Quartz 冲突）：
aliases: → 用 also_known_as:slug: → 由文件名决定 URLpublish: → 用 draft: true
常见问题速查
| 问题 | 解决 |
|---|
git clone 慢 | 加 --depth 1 |
| "missed comma" | YAML # 注释问题 |
| "ENOTEMPTY" | aliases: 冲突 |
| "Invalid URL" | baseUrl 为空 |
| 内容不更新 | 清 .quartz-cache；symlink 在 Win 改 copy |
| 图片不显示 | 检查路径，外链可直接用 |
| 中文乱码 | locale: "zh-CN" + 文件 UTF-8 |
脚本与配置
| 路径 | 用途 |
|---|
scripts/sync-content.sh | ai-wiki/wiki/ → quartz/content/ 同步 |
scripts/deploy.sh | 一键远程部署（build + rsync + HTTP 验证） |
scripts/nginx-llm-wiki.conf | nginx server block 模板 |
references/deployment-nginx-vps.md | VPS 部署完整手册 |
TODO
