Fonts

overview:

• Fine-grained Quartz font control
• Per-heading font families
• Quartz Themes font metadata discovery
• Google Fonts loading with weight/italic selection
• Obsidian default system font-stack fallback

Note

configuration:

• Plugin add/remove/configure workflow: Configuration

Why use Fonts?

problem:

• Quartz font variables:
  • --headerFont
  • --bodyFont
  • --codeFont
• Obsidian theme font variables:
  • --h1-font through --h6-font
  • --font-text
  • --font-monospace
• mismatch:
  • Quartz and Obsidian font systems do not bridge cleanly
  • Theme heading fonts can fail to render as intended

solution:

• Bridge Obsidian and Quartz font systems
• Emit unlayered CSS that overrides Quartz base heading styles
• Add per-heading font control beyond native Quartz/Obsidian behavior
• Optionally load Google Fonts with exact weight/italic control

Configuration

font_specification:

• string: CSS font-family
• object: Google Fonts loading controls

# String form
body: '"Inter", sans-serif'
 
# Object form (for Google Fonts weight/italic control)
body:
  name: Inter
  weights: [400, 600, 700]
  includeItalic: true

options:

Option	Type	Default	Description
title	FontSpecification	header value	Site title font family.
body	FontSpecification	Obsidian default	Body text font family.
header	FontSpecification	Obsidian default	Default heading font family for h1–h6.
code	FontSpecification	Obsidian default	Code/monospace font family.
interface	FontSpecification	Obsidian default	UI font family.
h1 – h6	FontSpecification	header value	Per-heading font family overrides.
useThemeFonts	boolean	true	Use Quartz Themes fonts as defaults when installed.
fontOrigin	string	"googleFonts"	"googleFonts" loads CDN fonts; "selfHosted" downloads/serves locally; "local" disables font loading.

Default options

quartz.config.yaml

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

Font resolution

priority:

• user config:
  • plugin options
• theme fonts:
  • from Quartz Themes, when installed
• fallback:
  • Obsidian default system stacks

User config (plugin options)
  → Theme fonts (from Quartz Themes, if installed)
    → Obsidian defaults (system font stacks)

headings:

h1 option → header option → theme --h1-font → theme font → Obsidian default

site_title:

title option → header option → theme font → Obsidian default

Usage with Quartz Themes

quartz_themes:

• When Quartz Themes is installed and enabled:
  • Fonts discovers theme font metadata automatically
  • Fonts uses theme fonts as defaults
  • Explicit Fonts options override theme fonts
• order:
  • requirement: Fonts runs after Quartz Themes
  • Quartz Themes defaultOrder: 10
  • Fonts defaultOrder: 60
  • handling: automatic plugin ordering

Warning

ordering:

• If Quartz Themes is enabled but has not run before Fonts, the console shows a warning
• Ensure Quartz Themes has a lower defaultOrder than Fonts

Usage without Quartz Themes

standalone:

• Fonts works without Quartz Themes
• fallback: Obsidian default system font stacks
• explicit fonts: plugin options

Examples

quartz.config.yaml

# Use theme fonts automatically (default behavior)
- source: github:quartz-community/fonts
  enabled: true
 
# Override just the heading font
- source: github:quartz-community/fonts
  enabled: true
  options:
    header: '"Playfair Display", serif'
 
# Full control with per-heading fonts
- 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'
 
# Load from Google Fonts automatically
- source: github:quartz-community/fonts
  enabled: true
  options:
    fontOrigin: googleFonts
    body: Inter
    header: Playfair Display
    code: JetBrains Mono
 
# Google Fonts with weight/italic control
- 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]
 
# Custom title font (separate from header)
- source: github:quartz-community/fonts
  enabled: true
  options:
    fontOrigin: googleFonts
    title: Abril Fatface
    header: Playfair Display
    body: Inter
    code: JetBrains Mono
 
# Self-hosted fonts (downloaded at build time, no external requests)
- source: github:quartz-community/fonts
  enabled: true
  options:
    fontOrigin: selfHosted
    body: Inter
    header: Playfair Display
    code: JetBrains Mono
 
# Ignore theme fonts entirely
- source: github:quartz-community/fonts
  enabled: true
  options:
    useThemeFonts: false
    body: '"Inter", sans-serif'

Self-Hosted Fonts

behavior:

• fontOrigin: selfHosted:
  • downloads fonts from Google Fonts during build
  • serves files from site static/fonts/
  • removes runtime requests to Google
  • produces a self-contained site

build_steps:

• Fetch Google Fonts CSS for configured fonts
• Download each font file:
  • .woff2
  • .woff
  • other provided formats
• Write font files to build output static/fonts/
• Generate quartz-fonts.css with @font-face rules pointing to local files

Note

requirement:

• Self-hosted fonts require baseUrl in Quartz configuration
• reason: generated CSS font URLs need absolute paths

quartz.config.yaml

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 Validation

validation:

• enabled_when:
  • fontOrigin: googleFonts
  • optional google-font-metadata package installed
• build_time_checks:
  • Google Fonts family names exist
  • Requested weights exist for each font
  • Requested italic support exists for each font
• warnings:
  • logged to console
  • do not block build

install:

npm install google-font-metadata

API

api:

• category:
  • Transformer
  • Emitter
• functions:
  • transformer: ExternalPlugin.Fonts()
  • emitter: ExternalPlugin.FontsEmitter()
• source: quartz-community/fonts
• install: npx quartz plugin add github:quartz-community/fonts