🪨 Quartz

One-liner: Quartz 5 turns Markdown, Obsidian-style knowledge, local plugin forks, and YAML layout rules into a fast static SSOT site. Treat it as a compiler pipeline, not a CMS.

flowchart LR
    A[📝 content/<br/>Markdown vault] --> B[🔧 transformers<br/>AST + metadata]
    B --> C[🧹 filters<br/>publish gate]
    C --> D[📄 page emitters<br/>routes/html]
    D --> E[🧩 layout/components<br/>sidebars/search]
    E --> F[🌐 public/<br/>deployable site]

1. ⚡ Quick Start

Goal	Command	Use When
Install deps	npm install	Fresh clone or dependency drift
Restore plugins	npx quartz plugin install --from-config	Config changed or clone missing plugin deps
Preview site	npx quartz build --serve	Local edit loop
Build site	npx quartz build	Production static output
Type/format gate	npm run check	Before publishing code/config changes
Test core	npm test	After compiler/plugin source changes
Deploy SSOT	~/deploy.sh	Publish ssot.0rk.de

Runtime invariant: Node >=22, npm >=10.9.2. If deploy breaks mysteriously, check runtime versions first.

2. 🧠 Mental Model

• Quartz is a compiler: input files become typed virtual files, then rendered pages, indexes, assets, and metadata.
• Content lives in content/: Markdown, folder notes, canvas files, bases, assets, and index pages are the source of truth.
• Config is declarative-first: quartz.config.yaml declares plugins, theme, layout, and site behavior.
• quartz.ts is the escape hatch: use it only for programmatic config loading/merging and advanced logic.
• Plugins are contracts: transformers parse/annotate, filters discard, emitters write outputs, component plugins place UI.
• Local forks are vendored plugins: source under quartz/local-plugins/<name>/; committed dist/ is required.

3. 🧭 File Map

Path	Job
content/index.md	Homepage and top-level navigation
content/knowledge/	Distilled know-how and cheat sheets
content/stack/	Stack-specific operating references
content/skills/gurus/	Specialist operating manuals
quartz.config.yaml	Site config, plugins, theme, layout
quartz.ts	Loads YAML config/layout into Quartz runtime
quartz/styles/custom.scss	Site-wide CSS overrides
quartz/local-plugins/	Local plugin forks with committed builds
public/	Generated output; do not hand-edit

4. 🧩 Pipeline

🔧 Transformers

They parse and enrich content before pages exist.

• obsidian-flavored-markdown → wikilinks, callouts, embeds, checkboxes.
• github-flavored-markdown → tables, strikethrough, task lists, autolinks.
• frontmatter-style metadata comes through YAML delimiters.
• crawl-links → internal link resolution.
• description → SEO/meta summaries.
• latex → KaTeX math.
• note-properties → selected frontmatter display.

🧹 Filters

They decide what survives the build.

• remove-draft excludes draft: true.
• unlisted-pages keeps pages out of indexes/feeds while still building them.
• explicit-publish exists but is disabled here; do not assume publish: true is required.

📄 Page Emitters

They materialize routes.

• content-page → normal Markdown pages.
• folder-page → folder index/list pages.
• tag-page → tag landing pages.
• canvas-page → Obsidian .canvas pages.
• bases-page → Obsidian Bases-style views.

🧱 Asset/Index Emitters

They emit site infrastructure.

• content-index → RSS + sitemap.
• search → Pagefind-powered search UI.
• graph → backlink graph.
• alias-redirects → redirect stubs from aliases.
• cname → custom domain marker.
• og-image → social preview images.

5. 🎛️ Config Rules

configuration:
  pageTitle: "0rk SSOT"
  baseUrl: ssot.0rk.de
  enableSPA: true
  enablePopovers: true
 
plugins:
  - source: github:quartz-community/example
    enabled: true
    options: {} # plugin-specific config lives here
    layout: # visual components only
      position: right
      priority: 10

Idiot-proof config checklist:

• Put plugin options under options: or Quartz may ignore them.
• Use layout.position only for component placement: left, right, beforeBody, afterBody, body, footer.
• Use higher layout.priority to render earlier/higher within a region.
• Keep baseUrl: ssot.0rk.de; feeds and canonical URLs depend on it.
• Keep ignorePatterns for private/templates/editor folders.
• Never hand-edit public/; rebuild instead.

6. 🖼️ Layout

Page type → layout.byPageType override → component layout rules → rendered frame

• Global groups: layout.groups.toolbar defines shared grouped component behavior.
• Page type overrides: layout.byPageType.folder/tag can exclude TOC/backlinks/reader mode.
• Responsive display: plugins can use display: all, desktop-only, or mobile-only.
• Folder labels: folder index.md frontmatter title becomes the Explorer label.
• 404 pages: strip sidebars by overriding beforeBody, left, and right.

7. 🧾 Content Rules

---
title: "🪨 Quartz 5 Masterclass"
description: "Short, search-friendly summary."
tags:
  - quartz
  - cheatsheet
aliases:
  - old-page-name
---

• Use title, description, tags, and aliases deliberately.
• Date keys are only created, modified, published; avoid fake modified because git supplies it.
• Use aliases when moving pages so redirect stubs preserve inbound links.
• Link files by shortest useful wiki path: [[quartz5]], [[QuartzGuru]], [[knowledge/cheatsheets|Cheat Sheets]].
• Link folders by folder path, not hidden implementation files: [[skills/gurus|Skill Docs]].
• Keep one clear H1 matching the page intent.

8. 🪻 Obsidian Parity

• Wikilinks: [[Target]], alias wikilinks, and anchors are handled by Obsidian-flavored Markdown.
• Callouts: native Obsidian callout blocks, including expanded/collapsed variants.
• Tasks: checkboxes and task metadata through Markdown plugins.
• Canvas: .canvas files render via local canvas-page.
• Bases: .base files render via bases-page.
• Backlinks: backlinks component renders in the right sidebar.
• Search: Pagefind search overlay.
• Graph: desktop graph component in the left sidebar.

Rule: Obsidian syntax is supported where configured, but static publishing wins. Anything requiring live Obsidian plugins must be precompiled or represented as static content.

9. 🔌 Local Plugins

flowchart LR
  Source["quartz/local-plugins/name"] -->|"source: ./quartz/local-plugins/name"| Config["quartz.config.yaml"]
  Source -->|"npm install && npm run build"| Dist["dist committed"]
  Config -->|"loader reads plugin"| Build["npx quartz build"]
  Dist --> Build

Fork recipe:

1. Copy plugin source into quartz/local-plugins/<name>/.
2. Point source: at ./quartz/local-plugins/<name>.
3. Build inside the plugin directory.
4. Commit dist/.
5. Configure using the directory basename as the option key.

Never edit plugin dist/ by hand. Edit source, rebuild, commit the generated output.

10. 🚀 Deploy

npm install
→ npx quartz plugin install --from-config
→ npm run check
→ npx quartz build
→ node generate-llmstxt.js
→ ~/deploy.sh

Production assumptions:

• Output directory is public/.
• Domain is ssot.0rk.de.
• Clean URL hosting needs an .html fallback:

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

11. 🧪 Debug Fast

Symptom	First Check	Likely Fix
Build fails on CI	Node/npm version	Use Node 22+ / npm 10.9.2+
Plugin missing	Plugin install state	npx quartz plugin install --from-config
Options ignored	YAML nesting	Move settings under options:
Page missing	Draft/unlisted/filter	Check draft, unlisted, plugin filters
Bad links	Link resolution	Prefer shortest wikilinks or clean relative Markdown
404 on clean URL	Web server fallback	Add $uri.html fallback
Local plugin works only locally	Missing committed dist/	Build plugin and commit output
Theme breaks in dark mode	Hardcoded styles	Move theme-aware CSS to custom.scss variables

12. 🛡️ Hard Rules

• ✅ Keep source of truth in content/, not generated public/.
• ✅ Use YAML config for declarative behavior; use TypeScript only when YAML cannot express it.
• ✅ Build and commit local plugin dist/.
• ✅ Keep docs high-density, linked, and frontmatter-complete.
• ✅ Preserve aliases when moving content.
• ✅ Verify with npm run check for code/config changes and npx quartz build for publish readiness.
• ❌ Do not fake dates.
• ❌ Do not bury plugin config outside options:.
• ❌ Do not add Mermaid init theme directives; let site theme handle rendering.
• ❌ Do not assume Obsidian-only live plugins work on the static site.

13. 🔗 Canon

• 🪨 Quartz 5 Reference — detailed stack reference.
• ✅ Quartz5 Checklist — live plugin registry and enabled status.
• 🪨 QuartzGuru — 0rk-specific operating manual.
• 📜 SSOT Bible — global SSOT rules and invariants.