Initial import
This commit is contained in:
Admin
@@ -0,0 +1,226 @@
|
||||
---
|
||||
title: Fonts
|
||||
description: Fine-grained font control with per-heading support, Google Fonts integration, and theme font discovery.
|
||||
tags:
|
||||
- plugin/transformer
|
||||
- plugin/emitter
|
||||
image:
|
||||
repository: "[quartz-community/fonts](https://github.com/quartz-community/fonts)"
|
||||
enabled: true
|
||||
required: false
|
||||
---
|
||||
|
||||
This plugin provides fine-grained control over fonts in your Quartz site. It supports per-heading font families, automatic theme font discovery when used with [Quartz Themes](https://github.com/saberzero1/quartz-themes), Google Fonts integration with automatic weight and italic loading, and falls back to Obsidian's default system font stacks.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
## Why use Fonts?
|
||||
|
||||
Quartz uses three CSS variables for fonts: `--headerFont`, `--bodyFont`, and `--codeFont`. Obsidian themes use a different system with per-heading variables (`--h1-font` through `--h6-font`), `--font-text`, and `--font-monospace`. These two systems don't bridge correctly, causing heading fonts to not render as themes intend.
|
||||
|
||||
Fonts solves this by:
|
||||
|
||||
1. Bridging the Obsidian and Quartz font systems
|
||||
2. Emitting **unlayered** CSS that correctly overrides Quartz's base heading styles
|
||||
3. Providing per-heading font control that neither system offers alone
|
||||
4. Optionally loading fonts from Google Fonts with fine-grained weight and italic control
|
||||
|
||||
## Configuration
|
||||
|
||||
Font options accept either a CSS font-family string or an object with Google Fonts loading control:
|
||||
|
||||
```yaml
|
||||
# String form
|
||||
body: '"Inter", sans-serif'
|
||||
|
||||
# Object form (for Google Fonts weight/italic control)
|
||||
body:
|
||||
name: Inter
|
||||
weights: [400, 600, 700]
|
||||
includeItalic: true
|
||||
```
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
| --------------- | ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| `title` | `FontSpecification` | `header` value | Font family for the site title. |
|
||||
| `body` | `FontSpecification` | Obsidian default | Font family for body text. |
|
||||
| `header` | `FontSpecification` | Obsidian default | Default font family for all headings (h1-h6). |
|
||||
| `code` | `FontSpecification` | Obsidian default | Font family for code and monospace elements. |
|
||||
| `interface` | `FontSpecification` | Obsidian default | Font family for UI elements. |
|
||||
| `h1` – `h6` | `FontSpecification` | `header` value | Per-heading font family overrides. |
|
||||
| `useThemeFonts` | `boolean` | `true` | Use fonts from [Quartz Themes](https://github.com/saberzero1/quartz-themes) as defaults when it is installed. |
|
||||
| `fontOrigin` | `string` | `"googleFonts"` | `"googleFonts"` to load from Google Fonts CDN, `"selfHosted"` to download and serve locally, `"local"` for no loading. |
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/fonts
|
||||
enabled: true
|
||||
options:
|
||||
useThemeFonts: true
|
||||
fontOrigin: googleFonts
|
||||
```
|
||||
|
||||
### Font resolution
|
||||
|
||||
Fonts are resolved using a priority chain:
|
||||
|
||||
```
|
||||
User config (plugin options)
|
||||
→ Theme fonts (from Quartz Themes, if installed)
|
||||
→ Obsidian defaults (system font stacks)
|
||||
```
|
||||
|
||||
For individual headings:
|
||||
|
||||
```
|
||||
h1 option → header option → theme --h1-font → theme font → Obsidian default
|
||||
```
|
||||
|
||||
For the site title:
|
||||
|
||||
```
|
||||
title option → header option → theme font → Obsidian default
|
||||
```
|
||||
|
||||
## Usage with Quartz Themes
|
||||
|
||||
When [Quartz Themes](https://github.com/saberzero1/quartz-themes) is installed and enabled, Fonts automatically discovers the theme's font metadata and uses it as defaults. Any options you explicitly set in Fonts will override the theme fonts.
|
||||
|
||||
Fonts must run **after** Quartz Themes. This is handled automatically by plugin ordering (Quartz Themes = 10, Fonts = 60).
|
||||
|
||||
> [!warning]
|
||||
> If Quartz Themes is enabled but hasn't run yet when Fonts executes, you'll see a warning in the console. Make sure Quartz Themes has a lower `defaultOrder` than Fonts.
|
||||
|
||||
## Usage without Quartz Themes
|
||||
|
||||
Fonts works standalone. Without a theme, it falls back to Obsidian's default system font stacks. You can set fonts explicitly via the plugin options.
|
||||
|
||||
## Examples
|
||||
|
||||
```yaml title="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
|
||||
|
||||
When `fontOrigin: selfHosted` is set, Fonts downloads fonts from Google Fonts during the build and serves them from your site's `static/fonts/` directory. This makes your site fully self-contained with no external requests to Google at runtime.
|
||||
|
||||
At build time, the plugin:
|
||||
|
||||
1. Fetches the Google Fonts CSS for your configured fonts
|
||||
2. Downloads each font file (`.woff2`, `.woff`, etc.)
|
||||
3. Writes the font files to `static/fonts/` in your build output
|
||||
4. Generates a `quartz-fonts.css` file with `@font-face` rules pointing to the local files
|
||||
|
||||
> [!note]
|
||||
> Self-hosted fonts require `baseUrl` to be set in your Quartz configuration, since font URLs in the CSS need an absolute path.
|
||||
|
||||
```yaml title="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
|
||||
|
||||
When `fontOrigin: googleFonts` is set and the optional [`google-font-metadata`](https://www.npmjs.com/package/google-font-metadata) package is installed, Fonts validates your font configuration at build time:
|
||||
|
||||
- Checks that font family names exist in Google Fonts.
|
||||
- Warns if requested weights are not available for a font.
|
||||
- Warns if italic is requested but the font doesn't support it.
|
||||
|
||||
Install it to enable validation:
|
||||
|
||||
```bash
|
||||
npm install google-font-metadata
|
||||
```
|
||||
|
||||
Validation warnings are logged to the console but do not block the build.
|
||||
|
||||
## API
|
||||
|
||||
- Category: Transformer, Emitter
|
||||
- Function name: `ExternalPlugin.Fonts()` (transformer), `ExternalPlugin.FontsEmitter()` (emitter).
|
||||
- Source: [`quartz-community/fonts`](https://github.com/quartz-community/fonts)
|
||||
- Install: `npx quartz plugin add github:quartz-community/fonts`
|
||||
Reference in New Issue
Block a user