# Quartz

Quartz is a static-site generator built by Jacky Zhao (jackyzha0) for publishing personal Markdown vaults as websites. The pitch is narrow on purpose: it's the publishing layer for [[digital-garden|digital gardens]]. Drop a folder of Markdown into `content/`, run `npx quartz build`, get a site with wikilinks, backlinks, full-text search, a graph view, and popover previews — the same affordances Obsidian users already rely on, served as static HTML.

Originally derived from Hugo, the project rewrote itself in TypeScript with a JSX-based component system. Source code ships in full to every user; there is no opaque CLI binary doing the rendering.

## What it does

The compile pipeline is: Markdown → unified/remark AST → plugin-driven transforms → JSX render → static HTML. Plugins exist at three stages — parsing, filtering, and emitting — and the standard ones do the work most digital-garden authors expect:

- Resolve `[[wikilinks]]` and `![[transclusions]]` (Obsidian-style)
- Render frontmatter properties, callouts, and Mermaid diagrams
- Build the backlinks index
- Generate the graph data for the in-page graph view
- Produce a lunr.js full-text search index served client-side
- Run KaTeX for LaTeX, Shiki for syntax highlighting

Page-level interactivity (search, graph, popovers, SPA routing) ships as small client bundles, not a framework. Page navigation runs through micromorph for SPA-style instant transitions without a full SPA's runtime cost.

## Obsidian compatibility

The compatibility surface is the differentiator. Most static-site generators treat Markdown as a lowest-common-denominator format and ignore Obsidian extensions. Quartz treats Obsidian Flavored Markdown as the input contract:

- Wikilinks resolve by filename across folders, just like Obsidian
- Transclusions render inline content from another file
- Callouts render with the same `> [!note]` syntax
- Frontmatter properties (tags, aliases, parent) are first-class
- Folder structure becomes URL structure
- Hidden files (prefixed `_`) and Obsidian's `.obsidian/` config are filtered automatically

The practical consequence: you can author in Obsidian, commit, push, and the published site looks like a styled version of what you saw locally. No translation step, no incompatible-syntax hunts.

## Customization tiers

Three explicit modes, called out in the philosophy page:

1. **Content-only.** Edit `content/`, leave everything else alone.
2. **Config-only.** Tweak `quartz.config.ts` (plugins, theme, metadata) and `quartz.layout.ts` (page structure — header, sidebar, footer composition).
3. **Source-level.** Modify any plugin or component directly. The project ships its full source as part of the install, so users can fork the rendering pipeline without forking a separate repo.

This is the same "ship the source, don't hide the engine" pattern as [[karing]] (sing-box fork shipped with the client) and [[mihomo]] (Clash fork). The Quartz-specific motivation is that personal sites are personal — defaults should be opinionated but not load-bearing.

## Build and host

`npx quartz build --serve` runs the dev server with hot reload on config changes and incremental rebuilds on content edits. Output is plain static HTML/CSS/JS suitable for any static host: GitHub Pages (the default path documented), Cloudflare Pages, Netlify, S3, self-hosted nginx, or a Docker image. The repo includes Dockerfile and docker-compose configs out of the box.

Build performance is a stated priority. Incremental rebuilds keep the iteration loop tight even on vaults with thousands of files; SPA routing keeps published pages feeling instantaneous after the first load.

## Philosophy

The philosophy page is unusually direct for a static-site generator. Three claims that drive the design:

- **A garden should be a true hypertext.** Quoting Mike Caulfield's "The Garden and the Stream" — Quartz rejects file-cabinet hierarchies and Zettelkasten-style upfront categorization. Thinking is rhizomatic, the publishing tool should be too.
- **A garden should be shared.** Hamming's "door open" quote is load-bearing. Half-baked notes published create feedback loops that fully private notes cannot.
- **A garden should be your own.** The three customization tiers exist so the tool fits both non-technical writers and senior developers without forcing either into the other's workflow.

The project explicitly sees itself as ["agentic software"](https://jzhao.xyz/posts/agentic-computing) — opinionated defaults, full user control, no lock-in.

## Tradeoffs

- **TypeScript and Node v22+ required.** Heavier toolchain than Hugo or Zola; trivial if you already have Node, friction if you don't.
- **Obsidian-shaped or nothing.** Quartz isn't a general-purpose SSG. If your content isn't a wiki-style vault, the default themes and components will feel over-equipped.
- **Plugin system, not theme marketplace.** Customization happens in code, not by dropping a theme folder in. Power-users love this; non-coders hit a wall faster than with Hugo themes.
- **Discord-first community.** Issue tracker is reasonably active but most live help happens on Discord, which is fine if you live there and worse if you don't.

## Repo

https://github.com/jackyzha0/quartz — 11,915 stars, 3,704 forks, MIT licensed, created 2021-07. Documentation site at [quartz.jzhao.xyz](https://quartz.jzhao.xyz) is itself built with Quartz, which is the cleanest possible demo.

## Related

- [[digital-garden]] — the publishing format Quartz exists to serve
- [[llm-wiki-pattern]] — Quartz is one viable publication target for an LLM-maintained wiki
- [[files-as-graph-database]] — Quartz publishes the graph as-is, preserving wikilink structure in the rendered site
- [[obsidian-ai-complete-guide]] — Huashu's vault uses similar conventions; Quartz would be a natural publication layer
- [[filesystem-is-graph-database]] — same underlying bet about Markdown + wikilinks scaling