🪨 Quartz5

Complete, zero-fluff reference guide for Quartz 5, a fast, modular, TypeScript/YAML-configured static site generator optimized for publishing digital gardens and Obsidian vaults.

---

1. 🚀 Quick Start

Essential CLI Commands

• Initialize project: Create a new Quartz workspace in the vault directory:

  npx quartz create

• Local development: Launch a local hot-reloading preview server:

  npx quartz build --serve

• Compile static files: Build optimized production HTML/CSS/JS assets to public/:

  npx quartz build

• Configuration validation: Run typechecks and code formatter checks:

  npm run check

Deployment Configuration

• Multi-Platform Target: Quartz builds static files that can be hosted on GitHub Pages, Cloudflare Pages, Netlify, or Vercel.
• Build Settings: Use the following standard configurations in host pipelines:
  • Build Command: npx quartz plugin install && npx quartz build
  • Output Directory: public
• Sitemap & RSS: Set baseUrl in quartz.config.yaml to configure feed sitemaps and XML paths correctly.

---

2. 🔧 Configuration

• Primary settings: Site-wide properties (theme colors, locale, fonts, and active plugins).
• JSON Schema: Supported editors validate syntax and catch formatting mistakes dynamically.

Configuration Template

# quartz.config.yaml
configuration:
  theme: "light"
  locale: "en-US"
  baseUrl: "ssot.0rk.de" # Root domain for feeds
 
layout:
  groups:
    toolbar: # Custom flexbox container
      direction: row # Flex direction
      gap: 0.5rem # Item spacing
  byPageType:
    canvas:
      template: minimal # Render frame override for Obsidian .canvas files
    content:
      template: default # Fallback layout frame
 
plugins:
  - source: github:quartz-community/explorer
    enabled: true
    layout:
      position: left # Section placement (left/right/beforeBody/afterBody/footer)
      priority: 100 # Priority order (higher numbers render higher up)
    options:
      title: "Navigation"
  - source: github:quartz-community/latex
    enabled: true
    layout:
      position: beforeBody
      priority: 50
    options:
      renderEngine: katex

Advanced Customization (quartz.ts)

• TypeScript Merging: Code-based configuration logic, plugins callbacks (sorting/filtering), and customizations are written in quartz.ts.
• Precedence rule: Programmatic rules in quartz.ts take precedence and merge directly with values in quartz.config.yaml.

---

3. 📦 Dependencies

System Requirements

• Runtimes: Requires Node.js v22+ and npm v10.9.2+ to support core ESM and plugin API execution.
• Module Sync: Restore all plugins listed in project configuration:

  npx quartz plugin install --from-config

Plugin Management CLI

• Add External Plugin: Install community-authored plugins directly from GitHub repositories:

  npx quartz plugin add <github-url>

• Dependency Updates: Resolve lockfile or fresh clone issues by updating all plugins:

  npx quartz plugin install --latest

Core Plugin Pipeline Stages

Category	Pipeline Phase	Purpose	Key Built-in Examples
Transformers	Parse & alter AST	Process Markdown syntax, parse frontmatter, extract links.	ObsidianFlavoredMarkdown, Frontmatter, CrawlLinks
Filters	Prune content	Exclude specific files (drafts, non-published) from building.	Drafts, ExplicitPublish
Emitters	Write outputs	Compile and emit static assets, search indices, and graph files.	Pagefind (Search), GraphView, Static

---

4. 💡 Best Practices

• Build Optimization: Disable computationally expensive emitters like GraphView to accelerate compilations in large vaults.
• Obsidian Link Format: Use clean Markdown relative links or native Wikilinks ([[VaultNote]]) for reliable link resolution.
• Asset Management: Keep images and attachments in a centralized vault folder to ensure path mappings build without errors.

---

5. 🚨 Gotchas & Warnings

• V4 Configuration Migrations: Version 4 utilizes TypeScript configs (quartz.config.ts); version 5 enforces quartz.config.yaml.
• Option Nesting Gotchas: Ensure option properties are nested under the options: block in your YAML, or Quartz will silently ignore them.
• C# Collision: Do not confuse Quartz SSG (Obsidian publishing) with the Quartz.NET scheduling library.
• Slow Builds: Speed up builds in heavy environments using the concurrency flag:

  npx quartz build --concurrency 8

• Failed Deployments: Outdated Node/npm engines are the leading cause of setup dependency errors in production environments.
• Nginx Clean URL 404s: Quartz references internal pages with clean URLs (e.g. /specs/omp), but emits them as .html files (e.g. /specs/omp.html). To prevent 404 routing errors, ensure the Nginx config has the .html fallback enabled:

  location / {
      try_files $uri $uri/ $uri.html =404;
  }

---

6. 🔍 Research

• Quartz Syncer: Obsidian companion plugin that pushes vaults and resolves/exports Dataview queries to static formats.
• Canvas Rendering: Core layout supports direct visual parsing and responsive display of Obsidian .canvas maps.
• Official Documentation: Quartz SSG Official Site
• Source Code: jackyzha0/quartz