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 社区插件Fontsgithub: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 插件正是为解决这一错位而设计它提供四方面能力桥接Obsidian 与 Quartz 两套字体系统让 Obsidian 主题的--h1-font等变量真正生效输出非分层unlayeredCSS从而正确覆盖 Quartz 基础标题样式提供两套体系单独都无法做到的逐级标题字体控制可选地从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插件完整接受以下配置选项选项类型默认值说明titleFontSpecificationheader值站点标题的字体。bodyFontSpecificationObsidian 默认正文文本的字体。headerFontSpecificationObsidian 默认所有标题h1–h6的默认字体。codeFontSpecificationObsidian 默认代码与等宽元素的字体。interfaceFontSpecificationObsidian 默认UI 元素的字体。h1–h6FontSpecificationheader值逐级标题字体覆盖。useThemeFontsbooleantrue已安装 Quartz Themes 时将其字体作为默认值。fontOriginstringgoogleFontsgoogleFonts从 Google Fonts CDN 加载selfHosted下载并本地托管local不加载。与核心字体配置的关系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_SERIFsystem-ui, Segoe UI, Roboto, ...与DEFAULT_MONOui-monospace, SFMono-Regular, ...见 theme.ts。与 Quartz Themes 配合使用当 Quartz Themes 已安装并启用时Fonts 会自动发现主题的字体元数据并作为默认值你在 Fonts options 中显式设置的任何字体都会覆盖主题字体。执行顺序是关键约束Fonts 必须在 Quartz Themes之后运行这一约束由插件默认执行顺序自动保证Quartz Themes 的defaultOrder为 10Fonts 为 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 发出任何外部请求。构建期流程分四步获取所配置字体的 Google Fonts CSS下载每个字体文件.woff2、.woff等将字体文件写入构建输出的static/fonts/生成包含指向本地文件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 MonoGoogle 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Quartz 字体精细化控制：Fonts 插件的完整配置指南
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 社区插件Fontsgithub: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 插件正是为解决这一错位而设计它提供四方面能力桥接Obsidian 与 Quartz 两套字体系统让 Obsidian 主题的--h1-font等变量真正生效输出非分层unlayeredCSS从而正确覆盖 Quartz 基础标题样式提供两套体系单独都无法做到的逐级标题字体控制可选地从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插件完整接受以下配置选项选项类型默认值说明titleFontSpecificationheader值站点标题的字体。bodyFontSpecificationObsidian 默认正文文本的字体。headerFontSpecificationObsidian 默认所有标题h1–h6的默认字体。codeFontSpecificationObsidian 默认代码与等宽元素的字体。interfaceFontSpecificationObsidian 默认UI 元素的字体。h1–h6FontSpecificationheader值逐级标题字体覆盖。useThemeFontsbooleantrue已安装 Quartz Themes 时将其字体作为默认值。fontOriginstringgoogleFontsgoogleFonts从 Google Fonts CDN 加载selfHosted下载并本地托管local不加载。与核心字体配置的关系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_SERIFsystem-ui, Segoe UI, Roboto, ...与DEFAULT_MONOui-monospace, SFMono-Regular, ...见 theme.ts。与 Quartz Themes 配合使用当 Quartz Themes 已安装并启用时Fonts 会自动发现主题的字体元数据并作为默认值你在 Fonts options 中显式设置的任何字体都会覆盖主题字体。执行顺序是关键约束Fonts 必须在 Quartz Themes之后运行这一约束由插件默认执行顺序自动保证Quartz Themes 的defaultOrder为 10Fonts 为 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 发出任何外部请求。构建期流程分四步获取所配置字体的 Google Fonts CSS下载每个字体文件.woff2、.woff等将字体文件写入构建输出的static/fonts/生成包含指向本地文件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 MonoGoogle 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考