Quartz 5 Configuration

Ultra-condensed guide for configuring Quartz 5 via quartz.config.yaml and quartz.ts.

🚀 Quick Start

• 🏁 Initialize: Execute npx quartz create inside your Obsidian vault directory.
• 🖥️ Serve: Launch local preview with npx quartz build --serve.
• ✅ Validate: Run npm run check or npx quartz check to verify configuration syntax.
• 🔄 Sync Dependencies: Restore modules using npx quartz plugin install --from-config.

🔧 Configuration

• 📄 File Formats: Version 5 enforces quartz.config.yaml for site settings and plugins. Programmatic logic and overrides reside in quartz.ts.
• 🧩 TypeScript Merging: Code-based logic in quartz.ts merges directly with YAML values. Programmatic rules always take precedence.
• 📝 JSON Schema: Configure editors to use the official schema to 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

Layout Groups & Templates

Feature	Details
📐 Layout Groups	Custom containers (e.g., toolbar) use Flexbox properties like direction and gap.
🖼️ Page Templates	Override frames via byPageType. Use template: minimal for .canvas files and template: default for content.
🧩 Plugin Rendering	Control placement using position (e.g., beforeBody) and display order via priority.

📦 Dependencies

• 💻 System Requirements: Node.js v22+ and npm v10.9.2+ are mandatory for core ESM support.
• 🌳 AST Processing: Core transformations rely on the unified, remark, and rehype ecosystems.
• 🎨 Canvas Extension: Add @quartz-community/canvas-page natively for JSON Canvas Spec 1.0 support.

💡 Best Practices

• 🗺️ Explorer mapFn: Rewrite node display names in quartz.ts. Use text.replace(/[\p{Emoji_Presentation}\p{Extended_Pictographic}\uFE0F]/gu, "") for safe Unicode emoji stripping.
• 🎨 Native Canvas Rendering: Place .canvas files directly into the content directory. Quartz processes interactive zooming and panning natively.
• ⚡ Concurrent Emitters: Design custom emitters as pure functions avoiding shared mutable state. This drastically accelerates build times.

🚨 Gotchas / Warnings

• ⚠️ Option Nesting: Ensure plugin settings sit under the options: block in YAML. Misplaced options are silently ignored.
• ⚠️ v4 Migration: Upgrading from v4 requires manually translating quartz.config.ts to quartz.config.yaml.
• ⚠️ Nginx Clean URLs: Quartz references clean URLs but emits .html files. Configure Nginx with try_files $uri $uri/ $uri.html =404; to prevent 404 errors.
• ⚠️ AST Deep Cloning: NEVER deep clone HAST trees during transformations. This neutralizes shallow-cloning and creates severe memory bloat.
• ⚠️ ASCII-only Regex: AVOID naive regex (e.g. /[^\x00-\x7F]/) for emoji stripping. This corrupts international characters and breaks valid filenames.
• ⚠️ Canvas Data Silos: DO NOT manually export Canvases to PNG/PDF/HTML. Rely entirely on the SSOT pipeline.

🔍 Research / References

Resource	Location
📚 Official Docs	Quartz SSG Official Site
💻 Source Code	jackyzha0/quartz
📜 Specifications	JSON Canvas Spec 1.0, ECMAScript Unicode Escapes