# 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](https://jzhao.xyz/posts/networked-thought) and notes as a website for free.

This fork adds first-class support for [org-roam](https://www.orgroam.com/) notes via [ox-hugo](https://ox-hugo.scripter.co/).

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

[Join the Discord Community](https://discord.gg/cRFFHYye7t)

## Quick Start

### Prerequisites

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

```bash
nix develop
```

All commands below must be run inside this shell.

```bash
npm install
```

### Building from org-roam notes

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

```bash
# 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:

1. **Wipe** `content/` clean
2. **Export** every `.org` file via `emacs --batch` + ox-hugo → Markdown
3. **Transform** — post-process the Markdown (citation resolution, etc.)
4. **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](https://retorque.re/zotero-better-bibtex/)
plugin installed, no extra configuration is needed — the pipeline detects it
automatically and links directly to the PDF in your library.

```bash
# 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:

```bash
# 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

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

## Sponsors

<p align="center">
  <a href="https://github.com/sponsors/jackyzha0">
    <img src="https://cdn.jsdelivr.net/gh/jackyzha0/jackyzha0/sponsorkit/sponsors.svg" />
  </a>
</p>