⚡ Concurrent Emitters: Design custom emitters as pure functions without shared mutable state. This maximizes concurrent pipeline throughput.
🪶 HAST Shallow-cloning: Use Object.assign({}, node) during AST transforms. This avoids the severe memory overhead of deep cloning massive trees.
🧹 Unicode Emoji Stripping: Use Explorer’s mapFn with /[\p{Emoji_Presentation}\p{Extended_Pictographic}\uFE0F]/gu. This safely strips emojis from node.displayName without breaking CJK text.
🎨 Native Canvas Rendering: Drop raw .canvas files directly into your content directory. Quartz handles interactive panning and zooming natively.
🚀 Build Optimization: Disable computationally expensive emitters like GraphView to accelerate huge vault compilations. Use npx quartz build --concurrency 8 for heavy environments.
🔗 Wikilinks Only: ALWAYS use native Wikilinks ([[VaultNote]]) for internal cross-referencing. Standard Markdown links break graph indexing and reliable link resolution.
📁 Asset Management: Centralize images and attachments in a single vault folder. This prevents path mapping errors during builds.
🚨 Gotchas & Warnings
💣 Deep Cloning AST: NEVER deep clone HAST trees. It neutralizes shallow-cloning optimizations and causes extreme memory bloat.
🧬 Mutating Shared HAST: Do not directly mutate node.children on shallow-cloned nodes. Always instantiate a new children array for structural changes.
🔣 RegEx ASCII Filtering: AVOID naive ASCII regexes like /[^\x00-\x7F]/ for emoji stripping. They destroy international characters and valid filenames.
📤 Canvas Manual Export: DO NOT export Canvases to PNG, PDF, or HTML. Let the SSOT architecture handle raw .canvas files natively.
🧱 Blocking Emitters: AVOID heavy synchronous fs operations in emitters. They block the Node.js event loop and destroy concurrency.
⚙️ V4 to V5 Migrations: Version 4 uses quartz.config.ts, but Version 5 strictly enforces quartz.config.yaml. Ensure you update your configuration structure (see 01-Configuration).
🪹 YAML Option Nesting: Ensure plugin properties are strictly nested under the options: block in your YAML file. Unnested options are silently ignored by Quartz.
📛 Name Collisions: Quartz SSG (Obsidian publishing) has nothing to do with the Quartz.NET (C#) scheduling library.
🛑 Node Version: Node.js v22+ is absolutely REQUIRED. Outdated engines crash AST transformations and emitters.
🌐 Nginx Clean URLs: Quartz emits .html files but references clean URLs internally. Your Nginx config MUST include try_files $uri $uri/ $uri.html =404; to prevent 404 errors.