Configuration

configuration:

• primary file: quartz.config.yaml
• standard edits: no coding required
• sections:
  • configuration: site-wide behavior, metadata, theme
  • plugins: content pipeline extensions

Tip

yaml_validation:

• Edit quartz.config.yaml in a YAML-aware editor such as VSCode.
• Detect syntax/schema errors before build.

quartz.config.yaml

configuration:
  pageTitle: "My Site"
  # ... general configuration
plugins:
  - source: github:quartz-community/some-plugin
    enabled: true
    # ... plugin entries

General Configuration

scope:

• Site-wide settings.

fields: pageTitle: - Site title - Used by RSS Feed pageTitleSuffix: - Browser-tab title suffix - Does not affect the page-top title enableSPA: - Enables SPA Routing enablePopovers: - Enables popover previews analytics: - Analytics provider - values: - null: disabled - { provider: 'google', tagId: '<your-google-tag>' }: Google Analytics - { provider: 'plausible' }: Plausible managed - { provider: 'plausible', host: 'https://<your-plausible-host>' }: Plausible self-hosted; include https:// - { provider: 'umami', host: '<your-umami-host>', websiteId: '<your-umami-website-id>' }: Umami - { provider: 'goatcounter', websiteId: 'my-goatcounter-id' }: GoatCounter managed - { provider: 'goatcounter', websiteId: 'my-goatcounter-id', host: 'my-goatcounter-domain.com', scriptSrc: 'https://my-url.to/counter.js' }: GoatCounter self-hosted - { provider: 'posthog', apiKey: '<your-posthog-project-apiKey>', host: '<your-posthog-host>' }: Posthog - { provider: 'tinylytics', siteId: '<your-site-id>' }: Tinylytics - { provider: 'cabin' }: Cabin - { provider: 'cabin', host: 'https://cabin.example.com' }: Cabin custom domain - { provider: 'clarity', projectId: '<your-clarity-id-code>' }: Microsoft Clarity; project ID appears at top of overview page - { provider: 'matomo', siteId: '<your-matomo-id-code>', host: 'matomo.example.com' }: Matomo; omit protocol - { provider: 'vercel' }: Vercel Web Analytics - { provider: 'rybbit', siteId: 'my-rybbit-id' }: Rybbit managed - { provider: 'rybbit', siteId: 'my-rybbit-id', host: 'my-rybbit-domain.com' }: Rybbit self-hosted locale: - i18n locale - date-format locale baseUrl: - Canonical site host/path for sitemaps and RSS absolute URLs - Usually deployed URL host, e.g. quartz.jzhao.xyz - Excludes protocol: no https:// or http:// - Excludes leading/trailing slashes - set*during_create: - Prompted by `npx quartz create` - CLI strips https://, http://, and trailing slashes - github_pages_without_custom_domain: - Include repository subpath - repository: jackyzha0/quartz - deployed URL: https://jackyzha0.github.io/quartz - baseUrl: jackyzha0.github.io/quartz - quartz_5: - Uses relative URLs whenever possible - Minimizes deployment-location coupling ignorePatterns: - glob patterns ignored under content - Used for private pages theme: - Site appearance - fontOrigin: - Font source - "googleFonts": default; loads through Google Fonts API; fastest with CDN caching - "local": downloads fonts and serves them from site; no external requests - cdnCaching: - true: default; uses Google CDN cache for fonts; usually faster - false: downloads fonts for self-contained site - typography: - Fonts; any Google Fonts family - title: site-title font; optional; defaults to header - header: heading font - code: inline/block code font - body: body font - colors: - light: page background - lightgray: borders - gray: graph links, heavier borders - darkgray: body text - dark: header text, icons - secondary: links, current graph node - tertiary: hover states, visited graph nodes - highlight: internal-link background, highlighted text, highlighted code lines - textHighlight: Markdown-highlighted text background

Plugins

model:

• Quartz plugins transform content through a typed pipeline.

quartz.config.yaml

plugins:
  - source: github:quartz-community/created-modified-date
    enabled: true
    order: 10 # controls execution order
  - source: github:quartz-community/syntax-highlighting
    enabled: true
    order: 20
  # ... more plugins

plugin_execution:

• category: derived from plugin manifest
• order: execution order within category

Note

ts_override:

• For advanced plugin configuration, modify quartz.ts.

quartz.ts

import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"
 
const config = await loadQuartzConfig({
  // override any configuration field here
})
export default config
export const layout = await loadQuartzLayout()

plugin_types: transformers: - Transformers map over content - examples: parse frontmatter, generate descriptions filters: - Filters filter content - example: exclude drafts emitters: - Emitters reduce content - examples: create RSS feed, create pages listing files by tag page_types: - Define rendering for page categories - examples: content pages, folder listings, tag listings - Each page type can use a different page frame for overall HTML structure

page_frame_override:

• layout.byPageType can set template for a specific page type.

quartz.config.yaml

layout:
  byPageType:
    canvas:
      template: minimal # Override the page frame for canvas pages

references:

• layout > Page Frames: available frames and frame-resolution rules

Internal vs External Plugins

plugin_sources: internal: - Bundled with Quartz - example: FrontMatter community: - Installed separately - Referenced by github:org/repo source in quartz.config.yaml

quartz.config.yaml

plugins:
  - source: github:quartz-community/explorer
    enabled: true
  - source: github:quartz-community/syntax-highlighting
    enabled: true
    options:
      theme:
        light: github-light
        dark: github-dark

Community Plugins

install_single:

• Adds plugin to quartz.config.yaml
• Installs plugin under .quartz/plugins/

npx quartz plugin add github:quartz-community/explorer

install_from_config:

• Installs all plugins referenced in config but missing locally
• Useful after cloning or in CI

npx quartz plugin install --from-config

prune:

• Removes installed plugins no longer referenced in config

npx quartz plugin prune

cli_notes:

• npx quartz plugin install --from-config supports --dry-run
• npx quartz plugin prune supports --dry-run
• Full reference: plugin CLI reference

Advanced Source Options

source_forms: string: - Common form - Supports simple GitHub plugin references

quartz.config.yaml

plugins:
  - source: github:quartz-community/explorer
    enabled: true

source_forms: object: - Use for repository subdirectories, branch/tag pins, or custom local plugin directory names

quartz.config.yaml

plugins:
  - source:
      repo: "https://github.com/user/repo.git"
      subdir: plugin
      ref: main
      name: my-plugin
    enabled: true

object_fields:

Field	Required	Description
repo	✅	Git repository URL (e.g. https://github.com/user/repo.git).
subdir	❌	Subdirectory within the repository that contains the plugin. Used for monorepo-style plugin repositories.
ref	❌	Git ref (branch or tag) to pin to. Equivalent to the #ref suffix on string sources.
name	❌	Override the directory name used in .quartz/plugins/. Defaults to the repository name.

Real-world example

quartz_themes:

• quartz-themes lives in repository subdirectory plugin/.
• Install with:

quartz.config.yaml

plugins:
  - source:
      name: quartz-themes
      repo: "https://github.com/saberzero1/quartz-themes.git"
      subdir: plugin
    enabled: true
    options:
      theme: "tokyo-night"
      mode: both

Tip

source_equivalence:

• github:user/repo#branch
• object form { repo, ref } use_object_form_when:
• subdir required
• name override required
• readability preferred

Usage

plugin_configuration:

• Customize Quartz by adding, removing, enabling/disabling, and reordering plugins in quartz.config.yaml
• plugin_entry_fields:
  • source
  • enabled
  • order
  • options

quartz.config.yaml

plugins:
  - source: github:quartz-community/note-properties
    enabled: true
    options:
      includeAll: false
      includedProperties:
        - description
        - tags
        - aliases
    order: 5
  - source: github:quartz-community/created-modified-date
    enabled: true
    options:
      priority:
        - frontmatter
        - git
        - filesystem
    order: 10
  - source: github:quartz-community/latex
    enabled: true
    options:
      renderEngine: katex
    order: 80

Note

yaml_limits:

• Some plugin options require JavaScript callbacks, e.g. custom sort/filter/map functions.
• YAML cannot express callbacks. solution:
• Use TS override in quartz.ts.

quartz.ts

import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"
import * as ExternalPlugin from "./.quartz/plugins"
 
ExternalPlugin.Explorer({
  mapFn: (node) => {
    node.displayName = node.displayName.toUpperCase()
    return node
  },
})
 
const config = await loadQuartzConfig()
export default config
export const layout = await loadQuartzLayout()

precedence:

• quartz.ts options merge with YAML options
• quartz.ts options take precedence placement:
• Put plugin overrides before loadQuartzConfig()
• Required because components instantiate during config loading references:
• Plugin-specific docs list supported callback options

references:

• Plugin list and options: plugin
• Custom plugins: making custom plugins

Fonts

yaml_font_config:

• Fonts accept simple string values in quartz.config.yaml.

quartz.config.yaml

configuration:
  theme:
    typography:
      title: Schibsted Grotesk # optional, defaults to header font
      header: Schibsted Grotesk
      body: Source Sans Pro
      code: IBM Plex Mono

advanced_font_config:

• Use TS override in quartz.ts for weights and italics.

quartz.ts

import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"
 
const config = await loadQuartzConfig({
  theme: {
    typography: {
      header: {
        name: "Schibsted Grotesk",
        weights: [400, 700],
        includeItalic: true,
      },
      body: "Source Sans Pro",
      code: "IBM Plex Mono",
    },
  },
})
export default config
export const layout = await loadQuartzLayout()

Tip

advanced_font_features:

• per-heading font control
• self-hosted fonts
• Obsidian theme font bridging plugin:
• Fonts
• Can download Google Fonts at build time
• Can serve fonts locally with fontOrigin: selfHosted
• Enables fully self-contained sites.