Quartz v4 — org-roam edition

"[One] who works with the door open gets all kinds of interruptions, but [they] also occasionally gets clues as to what the world is and what might be important." — Richard Hamming

Quartz is a set of tools that helps you publish your digital garden and notes as a website for free.

This fork adds first-class support for org-roam notes via ox-hugo.

🔗 Upstream documentation: https://quartz.jzhao.xyz/

Join the Discord Community

Quick Start

Prerequisites

This project uses Nix. Enter the development shell, which provides Node.js 22, Elixir, and Emacs with ox-hugo:

nix develop

All commands below must be run inside this shell.

npm install

Building from org-roam notes

Your org-roam notes live in a separate directory. Point NOTES_DIR at it:

# Export notes to content/ and build the site
NOTES_DIR=/path/to/notes npm run build:notes

# Export, build, and serve with hot reload
NOTES_DIR=/path/to/notes npm run serve:notes

# Export only (wipes content/ and re-exports all .org files)
NOTES_DIR=/path/to/notes npm run export

The export pipeline runs in four phases:

Wipe content/ clean
Export every .org file via emacs --batch + ox-hugo → Markdown
Transform — post-process the Markdown (citation resolution, etc.)
Index — generate a fallback index.md if none was exported

Citations (org-citar → Zotero links)

org-citar references ([cite:@key]) are resolved to clickable Zotero links. With Zotero running and the Better BibTeX plugin installed, no extra configuration is needed — the pipeline detects it automatically and links directly to the PDF in your library.

# Use a local .bib file as fallback when Zotero is not running
BIBTEX_FILE=/path/to/refs.bib NOTES_DIR=/path/to/notes npm run export

# Control warning verbosity for unresolved keys
CITATION_MODE=strict NOTES_DIR=/path/to/notes npm run export

Env var	Default	Purpose
`BIBTEX_FILE`	—	Path to `.bib` file for citation fallback
`ZOTERO_URL`	`http://localhost:23119`	Zotero Better BibTeX base URL
`CITATION_MODE`	`warn`	`silent` / `warn` / `strict`

Building without org-roam notes

If you manage content/ directly with Markdown files:

# Build the site
npx quartz build

# Build and serve with hot reload
npx quartz build --serve

The site is generated in public/. When serving, visit http://localhost:8080.

Development

npm run check    # type check + format check
npm run format   # auto-format with Prettier
npm run test     # run tests

3.2 KiB Raw Blame History