企业官网建设流程全解析

Quartz 字体精细化控制：Fonts 插件的完整配置指南

【免费下载链接】quartz🌱 a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz

本篇指南围绕 Quartz 社区插件Fonts（github:quartz-community/fonts）展开，它是实现站点字体细粒度控制的核心方案：支持逐级标题（h1–h6）独立字体、自动发现 Quartz Themes 主题字体元数据、从 Google Fonts 按需加载指定字重与斜体，并在构建期下载字体实现完全自托管。读完本文，你将掌握 Fonts 的全部配置项、字体解析优先级链、与 Quartz Themes 的协作顺序、自托管部署方式，以及如何在quartz.config.yaml中写出可实际运行的字体配置。

为什么要用 Fonts 插件：两个字体体系之间的桥

Quartz 核心通过三个 CSS 变量控制全局字体，这一点可以从核心样式与主题工具源码中直接看到：

• --headerFont：标题字体，被 base.scss 中的h1–h6及thead统一定义为font-family: var(--headerFont)；
• --bodyFont：正文字体，见 base.scss；
• --codeFont：代码与等宽元素字体，见 base.scss 与 base.scss。

而 Obsidian 主题采用的则是另一套体系：逐级标题变量--h1-font到--h6-font，以及--font-text、--font-monospace。在 Quartz 核心中，--font-text、--font-monospace、--font-interface只是简单映射到--bodyFont与--codeFont的别名（见 theme.ts），并不存在--h1-font这类逐级标题变量。

两套体系互不连通的结果是：当你在 Quartz 中套用 Obsidian 主题时，主题声明的标题字体无法按预期渲染——Quartz 的基础标题样式会把所有标题统一套上--headerFont，覆盖掉主题想要表达的逐级字体差异。

Fonts 插件正是为解决这一错位而设计，它提供四方面能力：

1. 桥接Obsidian 与 Quartz 两套字体系统，让 Obsidian 主题的--h1-font等变量真正生效；
2. 输出非分层（unlayered）CSS，从而正确覆盖 Quartz 基础标题样式；
3. 提供两套体系单独都无法做到的逐级标题字体控制；
4. 可选地从Google Fonts加载字体，并支持细粒度的字重与斜体控制。

安装与启用

Fonts 是一个同时具备Transformer与Emitter双类型的社区插件（关于插件分类可参考 插件总览）。使用 CLI 安装：

npx quartz plugin add github:quartz-community/fonts

该命令会把插件写入quartz.config.yaml，并安装到.quartz/plugins/目录（社区插件的安装流程详见 配置指南）。默认配置仅需两行：

- source: github:quartz-community/fonts enabled: true options: useThemeFonts: true fontOrigin: googleFonts

配置项总览

字体选项（FontSpecification）接受两种形式：CSS font-family 字符串，或带 Google Fonts 加载控制的对象：

# 字符串形式 body: '"Inter", sans-serif' # 对象形式（用于 Google Fonts 字重/斜体控制） body: name: Inter weights: [400, 600, 700] includeItalic: true

插件完整接受以下配置选项：

与核心字体配置的关系

Quartz 核心本身也提供configuration.theme.typography的title/header/body/code字体配置（见 configuration.md），对象形式的name/weights/includeItalic字段与 theme.ts 中FontSpecification的类型定义完全对应。但核心配置只作用于--headerFont/--bodyFont/--codeFont三个变量，不支持逐级标题覆盖、也不支持自托管。需要这些能力时，应使用 Fonts 插件。

字体解析优先级链

Fonts 按如下优先级链解析字体（数字越小优先级越高）：

用户配置（插件 options） → 主题字体（来自 Quartz Themes，如已安装） → Obsidian 默认（系统字体栈）

逐级标题的解析链为：

h1 选项 → header 选项 → 主题 --h1-font → 主题字体 → Obsidian 默认

站点标题的解析链为：

title 选项 → header 选项 → 主题字体 → Obsidian 默认

也就是说：插件 options 中显式设置的值拥有最高优先级；其次是主题声明的字体元数据；最后兜底的是 Obsidian 默认系统字体栈。Obsidian 默认字体栈即 Quartz 核心中的DEFAULT_SANS_SERIF（system-ui, "Segoe UI", Roboto, ...）与DEFAULT_MONO（ui-monospace, SFMono-Regular, ...），见 theme.ts。

与 Quartz Themes 配合使用

当 Quartz Themes 已安装并启用时，Fonts 会自动发现主题的字体元数据并作为默认值；你在 Fonts options 中显式设置的任何字体都会覆盖主题字体。

执行顺序是关键约束：Fonts 必须在 Quartz Themes之后运行，这一约束由插件默认执行顺序自动保证（Quartz Themes 的defaultOrder为 10，Fonts 为 60）。Quartz 加载器正是依据entry.order ?? manifest.defaultOrder ?? 50决定插件执行顺序（见 config-loader.ts）。

[!warning] 如果 Quartz Themes 已启用，但在 Fonts 执行时尚未运行，控制台会出现警告。请确保 Quartz Themes 的defaultOrder低于 Fonts。

不使用 Quartz Themes 时

Fonts 完全可以独立工作。未安装主题时，字体回退到 Obsidian 默认系统字体栈；你也可以直接通过插件 options 显式指定字体。

实战配置示例

以下示例全部可复制到quartz.config.yaml的plugins列表中：

# 自动使用主题字体（默认行为） - source: github:quartz-community/fonts enabled: true # 仅覆盖标题字体 - source: github:quartz-community/fonts enabled: true options: header: '"Playfair Display", serif' # 全量控制 + 逐级标题字体 - source: github:quartz-community/fonts enabled: true options: body: '"Inter", sans-serif' header: '"Playfair Display", serif' code: '"JetBrains Mono", monospace' h1: '"Playfair Display", serif' h2: '"Lora", serif' # 从 Google Fonts 自动加载 - source: github:quartz-community/fonts enabled: true options: fontOrigin: googleFonts body: Inter header: Playfair Display code: JetBrains Mono # Google Fonts 字重/斜体控制 - source: github:quartz-community/fonts enabled: true options: fontOrigin: googleFonts body: name: Inter weights: [400, 600, 700] includeItalic: true header: name: Playfair Display weights: [400, 700] code: name: JetBrains Mono weights: [400] # 独立于标题的站点标题字体 - source: github:quartz-community/fonts enabled: true options: fontOrigin: googleFonts title: Abril Fatface header: Playfair Display body: Inter code: JetBrains Mono # 自托管字体（构建时下载，无外部请求） - source: github:quartz-community/fonts enabled: true options: fontOrigin: selfHosted body: Inter header: Playfair Display code: JetBrains Mono # 完全忽略主题字体 - source: github:quartz-community/fonts enabled: true options: useThemeFonts: false body: '"Inter", sans-serif'

自托管字体：完全离线自足的站点

设置fontOrigin: selfHosted后，Fonts 会在构建期从 Google Fonts 下载字体，并从站点的static/fonts/目录提供，运行时不会向 Google 发出任何外部请求。

构建期流程分四步：

1. 获取所配置字体的 Google Fonts CSS；
2. 下载每个字体文件（.woff2、.woff等）；
3. 将字体文件写入构建输出的static/fonts/；
4. 生成包含指向本地文件@font-face规则的quartz-fonts.css。

这与 Quartz 核心的自托管逻辑一致：核心的 processGoogleFonts 通过正则解析 Google Fonts 样式表中fonts.gstatic.com的字体 URL，把.woff2/.woff/.ttf/.otf替换为https://${baseUrl}/static/fonts/${filename}.${extension}形式的本地地址并产出字体文件清单。

[!note] 自托管字体要求 Quartz 配置中设置baseUrl，因为 CSS 中的字体 URL 需要绝对路径（baseUrl的取值规则见 configuration.md，不含协议与前后的斜杠）。

configuration: baseUrl: "example.com" plugins: - source: github:quartz-community/fonts enabled: true options: fontOrigin: selfHosted body: Inter header: Playfair Display code: JetBrains Mono

Google Fonts 构建期校验

当fontOrigin: googleFonts且安装了可选的google-font-metadata包时，Fonts 会在构建期校验字体配置：

• 检查字体族名称是否存在于 Google Fonts；
• 对请求了某字体不支持的字重给出警告；
• 对请求了某字体不支持的斜体给出警告。

安装该包以启用校验：

npm install google-font-metadata

校验警告只输出到控制台，不会阻断构建。

以 TS 覆盖方式使用

社区插件在 TS 覆盖（quartz.ts）中通过ExternalPlugin命名空间引用（见 插件总览）。Fonts 暴露两个函数：ExternalPlugin.Fonts()（transformer）与ExternalPlugin.FontsEmitter()（emitter）。注意，quartz.ts中设置的选项与 YAML 合并，且 TS 选项优先级更高；插件覆盖必须放在loadQuartzConfig()之前（见 configuration.md）。

快速参考

• 类别：Transformer、Emitter
• 函数名：ExternalPlugin.Fonts()（transformer）、ExternalPlugin.FontsEmitter()（emitter）
• 安装命令：npx quartz plugin add github:quartz-community/fonts
• 默认启用：是（enabled: true）
• 必需：否（required: false）

对于逐级标题字体控制、自托管字体或 Obsidian 主题字体桥接等核心配置无法满足的场景，官方配置文档也明确指向 Fonts 插件作为推荐方案（见 configuration.md）。安装后结合 配置指南 的插件管理方式，即可在quartz.config.yaml中直接调整、增删或重排该插件，实现从正文、代码到每一个标题的精细化字体排版。

【免费下载链接】quartz🌱 a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz