101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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>
|