Quartz5 完全指南：现代化数字花园的构建与使用

Quartz5 是 Quartz v4.5.1 的现代化升级版本，由 @labspc 维护，专注于更智能、更友好的数字写作体验，助你轻松管理与发布内容，构建属于自己的现代化数字花园。

📋 目录

项目概述
核心特性对比
新增功能详解
技术架构升级
快速开始指南
Obsidian 集成使用
高级配置与定制
部署与发布
最佳实践
常见问题

🎯 项目概述

基本信息

版本：v5.0.0
基于：Quartz v4.5.1 by jackyzha0
维护者：labspc
技术栈：TypeScript + Preact + Node.js
许可证：MIT License with Commons Clause
仓库：github.com/labspc/quartz5

设计理念

Quartz5 秉承”AI 友好、用户至上”的设计理念，在保持原版 Quartz 优秀特性的基础上，重点加强了：

🧠 智能化工作流：集成 MCP 协议，支持自动化发布与内容管理
🏷️ 增强标签系统：提供可视化标签管理、批量操作和智能分析
💬 社区互动功能：内置留言板、评论系统和外链监测
🎨 现代化用户界面：响应式设计，支持深色模式和个性化定制
🚀 一键部署体验：无缝集成 GitHub + Vercel，实现零配置部署

⚡ 核心特性对比

Quartz4 vs Quartz5 功能矩阵

功能特性	Quartz4	Quartz5	说明
核心功能
Markdown 渲染	✅	✅	基础功能保持一致
双向链接	✅	✅	完全兼容 Obsidian 语法
标签系统	✅	🚀 强化	新增可视化管理、批量操作
全文搜索	✅	✅	FlexSearch 引擎
图谱视图	✅	✅	D3.js 驱动的知识图谱
新增特性
MCP 协议支持	❌	✅	AI 友好的自动化接口
留言板系统	❌	✅	Formbricks + GitHub Discussions
图片资源管理	❌	✅	智能图片索引和引用
外链监测	❌	✅	自动检测和管理外部链接
RSS 管理中心	❌	✅	可视化 RSS 内容管理
AI 训练文本生成	❌	✅	自动生成 llms.txt
回到顶部	❌	✅	浮动返回按钮
阅读模式	❌	✅	专注阅读体验
用户体验
SPA 路由	✅	✅	快速页面切换
悬浮预览	✅	✅	链接内容预览
响应式设计	✅	🚀 优化	更好的移动端体验
深色模式	✅	✅	主题切换
国际化支持	✅	🚀 扩展	更多语言支持

技术架构升级

技术层面	Quartz4	Quartz5	改进说明
构建系统
核心引擎	TypeScript + esbuild	TypeScript 5.8.3 + esbuild 0.25.5	性能优化，更快构建
前端框架	Preact	Preact 10.26.7	最新版本，Bug 修复
插件架构	三层架构	🚀 增强三层架构	新增 12+ 专用插件
新增依赖
MCP SDK	❌	@modelcontextprotocol/sdk	AI 协议集成
图片处理	❌	Sharp 0.34.2	高性能图片优化
社交图片	❌	Satori 0.13.1	动态 OG 图片生成
图表支持	D3.js	D3.js + Pixi.js	更丰富的可视化

🚀 新增功能详解

1. 增强标签系统 🏷️

Quartz5 将标签系统从简单的分类工具升级为强大的知识管理平台：

核心特性

可视化标签管理：提供列表、网格、图表三种视图模式
智能统计分析：自动计算标签使用频率、趋势和关联性
批量操作支持：支持标签重命名、合并、删除等批量操作
层级标签支持：支持 tech/backend/node.js 形式的嵌套标签
高级筛选器：按使用次数、创建时间、层级深度等条件筛选

使用示例

---
tags: 
  - tech/backend/node.js
  - project/quartz5
  - learning/documentation
---

管理界面

访问 /tags 页面即可使用标签管理器，支持：

🔍 实时搜索和过滤
📊 使用统计和趋势分析
✏️ 批量编辑和组织
📈 可视化标签网络图

2. 留言板系统 💬

集成了 Formbricks 和 GitHub Discussions 的双重留言系统：

Formbricks 集成

无需注册：访客可直接留言
智能表单：支持多种问题类型和条件逻辑
数据分析：自动收集和分析用户反馈
自定义样式：完全可配置的 UI 组件

// 在 quartz.config.ts 中配置
messagesConfig: {
  formbricks: {
    enabled: true,
    environmentId: "your-environment-id",
    appUrl: "https://app.formbricks.com",
    eventName: "message_button_clicked"
  }
}

GitHub Discussions 集成

公开透明：支持公开讨论和社区互动
Markdown 支持：完整的格式化文本支持
文件上传：支持图片和附件
邮件通知：自动通知新讨论

3. 图片资源管理 🖼️

全新的图片管理系统，让媒体资源组织更高效：

核心功能

自动索引：扫描并索引所有图片资源
智能引用：支持简化的图片引用语法
图片库页面：可视化浏览所有图片
懒加载优化：提升页面加载性能
多种尺寸：支持 small、medium、large 预设

增强语法

# 标准引用
![描述](./images/photo.jpg)
 
# 简化引用（Quartz5 新增）
@img[photo.jpg]
@img[photo.jpg|medium]
@img[library/tech/architecture-diagram.png|large]

4. 外链监测系统 🔗

自动检测和管理网站中的所有外部链接：

功能特点

自动发现：扫描内容中的所有外链
健康检查：定期检测链接有效性
分类管理：按域名、类型自动分类
统计报告：提供详细的链接使用统计

访问方式

访问 /links 页面查看外链监测报告。

5. RSS 管理中心 📡

专业的 RSS 内容管理和分析平台：

主要功能

内容预览：实时预览 RSS 订阅内容
订阅分析：统计订阅量和点击率
格式验证：确保 RSS 格式正确性
SEO 优化：自动生成搜索引擎友好的描述

配置示例

Plugin.ContentIndex({
  enableRSS: true,
  rssLimit: 15,
  rssLanguage: "zh-CN",
  rssCopyright: "© 2025 labspc",
  rssImage: {
    url: "https://labspc.com/static/icon.png",
    title: "labspc",
    width: 96,
    height: 96
  }
})

6. MCP 协议支持 🤖

集成 Model Context Protocol，实现 AI 友好的内容管理：

应用场景

自动发布：通过 API 自动发布内容
内容同步：与其他平台无缝同步
AI 辅助：支持 AI 工具读取和分析内容
编程接口：提供完整的编程接口

7. AI 训练文本生成 🧠

自动生成 llms.txt 文件，为 AI 训练提供结构化数据：

生成内容

网站结构：完整的网站目录结构
内容摘要：每篇文章的结构化摘要
标签索引：所有标签的分类索引
链接图谱：内部链接关系图

8. 用户体验增强 ✨

回到顶部按钮

智能显示：滚动一定距离后自动显示
平滑动画：丝滑的回到顶部动画
自适应位置：响应式位置调整

阅读模式

专注体验：隐藏侧边栏和导航，专注内容
自定义快捷键：支持键盘快捷键切换
记忆偏好：自动记住用户偏好设置

🛠️ 技术架构升级

插件系统增强

Quartz5 在保持原有三层插件架构的基础上，新增了 12+ 专用插件：

新增转换器 (Transformers)

ExternalLinks：外部链接处理和图标添加
ImageReferences：图片引用语法扩展

新增生成器 (Emitters)

ImagesPage：图片库页面生成
MessagesPage：留言板页面生成
LinksPage：外链监测页面生成
RSSPage：RSS 管理页面生成
LLMsTxt：AI 训练文本生成
UserAssets：用户资源管理

构建性能优化

优化项目	改进效果	技术实现
增量构建	构建速度提升 60%	智能文件依赖分析
并发处理	多核CPU利用率提升	Worker Pool 架构
缓存策略	重构建时间减少 80%	多层缓存机制
代码分割	首屏加载提升 40%	动态 import + 懒加载

🚀 快速开始指南

环境要求

在开始之前，请确保您的系统满足以下要求：

Node.js: >= v22.0.0
npm: >= v10.9.2
Git: 最新版本
操作系统: Windows / macOS / Linux

安装步骤

1. 克隆项目

# 克隆 Quartz5 仓库
git clone https://github.com/labspc/quartz5.git
cd quartz5
 
# 安装依赖
npm install

2. 初始化内容

# 运行初始化命令
npx quartz5 create
 
# 按照提示选择：
# ✔ 是否清空当前内容？ › 否
# ✔ 选择一个配置预设 › 个人数字花园
# ✔ 是否启用高级功能？ › 是

3. 开发预览

# 启动开发服务器
npm run quartz5 build --serve
 
# 或使用简化命令
npm run docs

服务器启动后，在浏览器中访问 http://localhost:8080 即可预览您的网站。

目录结构

安装完成后，您将看到以下目录结构：

quartz5/
├── content/                 # 📝 内容目录
│   ├── tech/               # 技术相关内容
│   ├── life/               # 生活笔记
│   ├── books/              # 读书笔记
│   ├── movies/             # 电影相关
│   ├── essays/             # 专题长文
│   ├── ideas/              # 灵感记录
│   ├── radar/              # 技术热点
│   └── inbox/              # 快速记录
├── images/                 # 🖼️ 图片资源
├── quartz/                 # ⚙️ 核心引擎
├── docs/                   # 📚 文档
├── quartz.config.ts        # 🔧 主配置文件
├── quartz.layout.ts        # 🎨 布局配置
└── package.json           # 📦 依赖管理

基础配置

编辑 quartz.config.ts 文件进行基础配置：

const config: QuartzConfig = {
  configuration: {
    pageTitle: "您的网站名称",
    siteDescription: "您的网站描述",
    baseUrl: "yoursite.com",
    
    // 启用核心功能
    enableSPA: true,
    enablePopovers: true,
    
    // 分析工具
    analytics: {
      provider: "plausible", // 或 "google", "umami"
    },
    
    // 语言设置
    locale: "zh-CN", // 或 "en-US"
  }
}

🧠 Obsidian 集成使用

Quartz5 专为 Obsidian 用户设计，提供无缝的工作流集成：

核心兼容特性

1. 双向链接支持

# 在 Obsidian 中的链接语法完全兼容
[[其他笔记的标题]]
[[笔记标题|显示文字]]
[[笔记标题#标题锚点|标题锚点]]

2. 块引用和嵌入

# 引用整个笔记
![[笔记标题]]
 
# 引用特定章节
![[笔记标题#章节标题|章节标题]]
 
# 引用代码块
```python
# 这里的代码会被语法高亮
def hello_world():
    print("Hello, Quartz5!")

3. 标签系统

---
tags:
  - tech/frontend/react
  - project/quartz5
  - #learning  # 支持 # 语法
---
 
正文中也可以使用 #标签 语法。

4. Callouts 支持

> [!note] 笔记
> 
> 这是一个笔记块
 
> [!warning] 警告
> 
> 这是一个警告块
 
> [!tip] 提示
> 
> 这是一个提示块

Obsidian 插件推荐

为了更好地与 Quartz5 协作，推荐安装以下 Obsidian 插件：

必装插件

插件名称	功能	用途
Templater	模板引擎	自动生成 Front Matter
Tag Wrangler	标签管理	批量编辑和组织标签
Quick Switcher++	快速跳转	高效导航和搜索
Obsidian Git	Git 集成	自动同步到 GitHub

插件名称	功能	用途
Calendar	日历视图	按日期组织笔记
Dataview	数据查询	动态生成内容列表
Excalidraw	绘图工具	创建图表和示意图
Advanced Tables	表格编辑	高效编辑 Markdown 表格

内容组织策略

建议的文件夹结构

Obsidian Vault/
├── 00-Inbox/              # 快速记录
├── 01-Daily/              # 日记
├── 02-Areas/              # 生活领域
│   ├── Tech/
│   ├── Books/
│   └── Health/
├── 03-Resources/          # 参考资料
├── 04-Archives/           # 归档内容
└── templates/             # 模板文件

Front Matter 模板

创建以下模板文件来标准化 Front Matter：

# templates/blog-post.md
---
title: "{{title}}"
description: ""
tags: 
  - 
date: {{date:YYYY-MM-DD}}
modified: {{date:YYYY-MM-DD}}
draft: false
---
 
# {{title}}
 
## 概述
 
 
 
## 详细内容
 
 
 
## 总结

图片和资源管理

在 Obsidian 中引用图片

# 标准语法
![图片描述](../images/tech/architecture/system-design.png)
 
# Quartz5 增强语法（发布后生效）
@img[system-design.png|large]

发布配置

设置发布过滤器

在 Obsidian 的设置中，可以配置哪些笔记需要发布：

# 在 Front Matter 中控制发布
---
publish: true    # 发布到网站
draft: false     # 不是草稿
private: false   # 不是私密笔记
---

自动化工作流

使用 GitHub Actions 实现自动化：

# .github/workflows/publish.yml
name: 发布到 Quartz5
on:
  push:
    branches: [ main ]
  
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: 构建并部署
        uses: ./.github/actions/quartz5-deploy

🔧 高级配置与定制

主题定制

Quartz5 支持深度的主题定制：

颜色主题配置

// quartz.config.ts
theme: {
  colors: {
    lightMode: {
      light: "#faf8f8",
      secondary: "#284b63",
      tertiary: "#84a59d",
    },
    darkMode: {
      light: "#161618",
      secondary: "#7b97aa", 
      tertiary: "#84a59d",
    }
  }
}

字体配置

typography: {
  header: "Schibsted Grotesk",  // 标题字体
  body: "Source Sans Pro",      // 正文字体
  code: "IBM Plex Mono",        // 代码字体
}

组件定制

自定义页面布局

// quartz.layout.ts
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.Breadcrumbs(),
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TagList(),
  ],
  left: [
    Component.PageTitle(),
    Component.Search(),
    Component.Darkmode(),
    Component.Explorer(),
  ],
  right: [
    Component.Graph(),
    Component.TableOfContents(),
    Component.Backlinks(),
  ],
}

添加自定义组件

// 创建自定义组件
const CustomStats: QuartzComponent = () => {
  return (
    <div class="custom-stats">
      <h3>网站统计</h3>
      <p>文章数量: {articleCount}</p>
      <p>标签数量: {tagCount}</p>
    </div>
  )
}

插件配置

高级插件配置示例

plugins: {
  transformers: [
    Plugin.FrontMatter(),
    Plugin.CreatedModifiedDate({
      priority: ["frontmatter", "git", "filesystem"],
    }),
    Plugin.SyntaxHighlighting({
      theme: {
        light: "github-light",
        dark: "github-dark", 
      },
      keepBackground: false,
    }),
    Plugin.ObsidianFlavoredMarkdown({
      enableInHtmlEmbed: false,
      enableYouTubeEmbed: true,
      enableVideoEmbed: true,
    }),
    Plugin.ImageReferences({
      enableLibraryReferences: true,
      defaultSize: 'medium',
      enableLazyLoading: true,
    }),
  ],
}

🚀 部署与发布

部署选项对比

部署平台	适用场景	优势	限制
Vercel	个人/小团队	零配置、自动部署、全球CDN	免费版有流量限制
Netlify	开源项目	丰富插件、表单处理	构建时间限制
GitHub Pages	简单需求	完全免费、GitHub集成	功能相对简单
自建服务器	企业用户	完全控制、无限制	需要运维知识

Vercel 部署（推荐）

一键部署

手动部署步骤

Fork Quartz5 仓库
登录 Vercel 控制台
点击 “New Project” 并选择您的仓库

配置构建设置：

Build Command: npm run build
Output Directory: public
Install Command: npm install

点击 “Deploy” 完成部署

环境变量配置

# 在 Vercel 控制台设置环境变量
NODE_VERSION=22
NPM_VERSION=10.9.2

GitHub Pages 部署

创建 .github/workflows/deploy.yml：

name: Deploy Quartz5 to GitHub Pages
 
on:
  push:
    branches: [ main ]
  workflow_dispatch:
 
permissions:
  contents: read
  pages: write
  id-token: write
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build
        run: npx quartz5 build
 
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public
 
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

自定义域名配置

DNS 配置

为您的域名添加以下 DNS 记录：

# A 记录指向 Vercel
@    A     76.76.19.61
@    A     76.76.19.62
 
# CNAME 记录
www  CNAME your-site.vercel.app

SSL 证书

Vercel 和 Netlify 都会自动为您的自定义域名提供免费的 SSL 证书。

🌱 最佳实践

写作规范

文件命名规范

# 推荐的文件命名方式
good-file-name.md           # ✅ 使用小写和连字符
2025-01-28-daily-note.md    # ✅ 日期前缀
tech/react-hooks-guide.md   # ✅ 分类路径

# 避免的命名方式
Bad File Name.md            # ❌ 空格和大写
file_with_underscores.md    # ❌ 下划线

Front Matter 标准化

---
title: "明确的标题"
description: "简洁的描述（建议 120-160 字符）"
tags: 
  - category/subcategory
  - specific-topic
date: 2025-01-28
modified: 2025-01-28
draft: false
author: "作者名称"
---

性能优化

图片优化

# 使用 WebP 格式
![优化的图片](./images/optimized.webp)
 
# 设置合适的尺寸
@img[large-diagram.png|medium]  # 而不是 large
 
# 使用懒加载
![懒加载图片](./images/below-fold.jpg){loading=lazy}

内容优化

控制文章长度：单篇文章建议 1000-3000 字
合理使用标签：每篇文章 3-8 个标签
优化链接密度：适度使用内部链接
定期清理：删除无用的草稿和文件

SEO 优化

页面优化

// quartz.config.ts
configuration: {
  // 确保每个页面都有独特的标题
  pageTitle: "您的网站 - 专业的知识分享平台",
  
  // 优化描述
  siteDescription: "分享技术见解、读书笔记和生活感悟的个人数字花园",
  
  // 设置正确的语言
  locale: "zh-CN",
  
  // 配置基础URL
  baseUrl: "https://yoursite.com",
}

社交分享优化

// 启用 OG 图片生成
Plugin.CustomOgImages({
  // 自定义社交分享图片
})

维护策略

定期维护清单

每周：检查外链健康状态 (/links 页面)
每月：分析标签使用情况并优化 (/tags 页面)
每季度：备份全部内容到多个位置
每年：评估和更新主题配置

内容审核

# 检查构建错误
npm run check
 
# 预览构建结果
npm run quartz5 build --serve
 
# 格式化代码
npm run format

🤔 常见问题

安装和配置问题

Q: Node.js 版本不兼容怎么办？

A: Quartz5 要求 Node.js >= v22，建议使用 nvm 管理版本：

# 安装 nvm（如果尚未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
 
# 安装并使用 Node.js 22
nvm install 22
nvm use 22

Q: 构建过程中出现内存不足错误？

A: 增加 Node.js 内存限制：

# 临时解决
NODE_OPTIONS="--max-old-space-size=4096" npm run build
 
# 或在 package.json 中设置
"scripts": {
  "build": "NODE_OPTIONS='--max-old-space-size=4096' npx quartz5 build"
}

内容管理问题

Q: 如何批量修改标签？

A: 使用 Quartz5 的标签管理器：

访问 /tags 页面
使用批量操作工具
或使用正则表达式批量替换

Q: 图片无法显示怎么办？

A: 检查以下几点：

图片路径是否正确
图片文件是否存在于 images/ 目录
是否使用了正确的引用语法
检查文件权限和大小限制

Q: 双向链接不生效？

A: 确保：

使用正确的 [[]] 语法
目标文件存在于 content/ 目录
文件名匹配（区分大小写）
重新构建项目

部署和发布问题

Q: Vercel 部署失败？

A: 常见解决方案：

检查 Node.js 版本设置
确认 build 命令正确
查看构建日志中的具体错误
检查环境变量配置

Q: 自定义域名配置问题？

A: 步骤检查：

DNS 记录是否正确配置
等待 DNS 传播（可能需要 24-48 小时）
检查 SSL 证书状态
确认域名服务商设置

性能优化问题

Q: 网站加载速度慢？

A: 优化建议：

压缩图片（使用 WebP 格式）
减少单页内容量
启用浏览器缓存
使用 CDN 加速

Q: 搜索功能不准确？

A: 搜索优化：

确保内容有合适的标题和描述
使用相关的标签和关键词
定期重建搜索索引

高级功能问题

Q: 留言板不显示？

A: 检查配置：

// 确保在 quartz.config.ts 中正确配置
messagesConfig: {
  enabled: true,
  formbricks: {
    enabled: true,
    environmentId: "your-env-id",
  }
}

Q: MCP 协议如何使用？

A: MCP 主要用于 AI 工具集成：

提供 API 接口供 AI 工具访问
支持自动化内容同步
详细使用方法请参考 MCP 文档

📚 延伸阅读

🙏 致谢

感谢以下项目和贡献者：

原作者: jackyzha0 - Quartz 原始项目
维护者: labspc - Quartz5 开发和维护
社区贡献者: 所有为 Quartz5 项目做出贡献的开发者

📄 许可证

本指南基于 MIT License with Commons Clause 发布。

简要说明：

✅ 个人和商业使用
✅ 修改和定制
✅ 分发和分享
❌ 直接销售 Quartz5 本身

最后更新：2025-06-23
版本：v1.0

labspc

Explorer