配置与本地构建

学习目标

掌握 quartz.config.yaml 的核心配置项
学会调整站点主题和布局
能够在本地预览网站效果

前置条件

完成 01_环境准备与quarts安装
内容已放入 content/ 目录

1. 站点配置文件

Quartz v5 的核心配置是 quartz.config.yaml（注意是 YAML 格式，不是 TypeScript）。

基础配置

configuration:
  pageTitle: "我的网站" # 站点标题
  pageTitleSuffix: " | 我的网站" # 浏览器标签后缀
  enableSPA: true # 启用 SPA 无刷新导航
  enablePopovers: true # 启用弹出预览
  analytics: null # 统计（null=关闭）
  locale: zh-CN # 语言
  baseUrl: 用户名.github.io/仓库名 # 部署域名（不含 https://）

忽略规则

ignorePatterns 控制哪些目录不参与构建：

ignorePatterns:
  - .obsidian # Obsidian 配置
  - .vscode # VS Code 配置
  - .doc # 内部文档
  - Clippings # 网页剪藏
  - template # 笔记模板
  - private # 私有笔记

重要：Quartz 不会自动忽略点开头的文件（如 .doc/），所有不发布的目录都需要显式声明。

主题配置

theme:
  fontOrigin: googleFonts # 字体来源
  cdnCaching: true # CDN 缓存
  typography:
    header: Noto Sans SC # 标题字体
    body: Noto Sans SC # 正文字体
    code: JetBrains Mono # 代码字体
  colors:
    lightMode:
      light: "#faf8f8" # 页面背景
      dark: "#2b2b2b" # 标题文字
      secondary: "#284b63" # 链接颜色
      # ... 其他颜色
    darkMode:
      # 暗色模式配色

2. 插件系统

Quartz v5 的插件是独立安装的社区包，在配置中通过 source 引用：

plugins:
  - source: "@quartz-community/obsidian-flavored-markdown"
    enabled: true
    order: 30
  - source: "@quartz-community/latex"
    enabled: true
    options:
      renderEngine: katex
    order: 80

常用插件

插件	功能	建议
`obsidian-flavored-markdown`	支持 wikilink、callout	✅ 必开
`latex`	数学公式渲染	✅ 必开
`syntax-highlighting`	代码语法高亮	✅ 必开
`table-of-contents`	自动生成目录	✅ 推荐
`graph`	关系图谱	✅ 推荐
`search`	全文搜索	✅ 推荐
`backlinks`	反向链接	✅ 推荐
`explorer`	左侧文件树	✅ 推荐
`canvas-page`	Canvas 文件渲染	✅ 推荐
`bases-page`	Base 文件渲染	✅ 推荐
`citations`	文献引用	❌ 按需

布局控制

每个插件可指定显示位置：

- source: "@quartz-community/explorer"
  enabled: true
  layout:
    position: left # left / right / beforeBody / afterBody
    priority: 50 # 数字越小越靠上
- source: "@quartz-community/table-of-contents"
  enabled: true
  layout:
    position: right
    priority: 30

3. 本地构建预览

# 完整构建
npx quartz build
 
# 构建并启动开发服务器（热重载）
npx quartz build --serve

浏览器打开 http://localhost:8080 即可预览。

修改 content/ 下的笔记或 quartz.config.yaml 后，保存即可自动刷新。

4. 首页设置

Quartz 默认以 content/index.md 作为首页。如果没有，会自动生成一个。你也可以自定义：

---
title: "首页标题"
description: "首页描述"
---
 
# 欢迎来到我的网站
 
这里是首页内容。

扩展阅读

常见问题

Q: 修改配置后没有生效？

确保修改的是 quartz.config.yaml，且格式正确。YAML 对缩进敏感，建议使用支持 YAML 校验的编辑器。

Q: 本地预览中文乱码？

Quartz 默认 UTF-8 编码，一般不会乱码。如果出现，检查 locale: zh-CN 是否配置。

Q: 如何关闭不需要的功能？

在 quartz.config.yaml 中将对应插件的 enabled 设为 false，或直接删除该插件条目。

练习任务

尝试修改 pageTitle 为你的站点标题
调整主题颜色为自己喜欢的配色
运行 npx quartz build --serve 本地预览
尝试开启/关闭几个插件观察效果

验收清单

能看懂 quartz.config.yaml 的各配置项
知道如何修改站点标题和主题
了解插件系统的用法
能成功在本地预览网站

Obsidian 教程

探索

02_配置与本地构建