Quartz Setup Guide

Quartz is a static site generator for publishing Obsidian notes as a website.

Related: Cloudflare | Takopi | Secrets

Installation

# Clone Quartz
git clone https://github.com/jackyzha0/quartz.git
cd quartz
 
# Install dependencies (requires Node.js 22+)
npm install

Configuration

Link Content Folder

Option 1: Symlink (development)

rm -rf content
ln -s /path/to/your/obsidian-vault content

Option 2: Copy content (production)

rm -rf content
cp -r /path/to/your/obsidian-vault content

Configure quartz.config.ts

Key settings:

const config: QuartzConfig = {
  configuration: {
    pageTitle: "Your Site Title",
    enableSPA: true,
    enablePopovers: true,
    analytics: null,
    locale: "en-US",
    baseUrl: "yourdomain.com",
    // ...
  },
  plugins: {
    // Disable OG images if you get font fetch errors
    emitters: [
      // Plugin.CustomOgImages(), // Comment out if causing issues
      Plugin.AliasRedirects(),
      Plugin.ComponentResources(),
      // ...
    ],
  },
}

Building

# Build site
npx quartz build
 
# Build and serve locally
npx quartz build --serve --port 8090
 
# Output is in ./public/

Syncing (Git-based workflow)

Setup Remote

# Add your repo as origin
git remote set-url origin git@github.com:YOUR_USERNAME/YOUR_REPO.git
 
# Keep upstream for Quartz updates
git remote add upstream https://github.com/jackyzha0/quartz.git

Fix for quartz sync

Quartz 4.5.2 has a bug with --autostash. Fix in quartz/cli/helpers.js:

// Change this line (~line 36):
const flags = ["--no-rebase", "--autostash", "-s", "recursive", "-X", "ours", "--no-edit"]
 
// To this (remove --autostash):
const flags = ["--no-rebase", "-s", "recursive", "-X", "ours", "--no-edit"]

Sync Command

npx quartz sync

This will:

1. Commit content changes
2. Pull upstream changes
3. Push to your repo

SSH Key Setup (for private repos)

# Generate key for this repo
ssh-keygen -t ed25519 -C "your-email@example.com" -f ~/.ssh/github_repo_name
 
# Add to SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/github_repo_name
 
# Configure SSH
cat >> ~/.ssh/config << 'EOF'
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_repo_name
    IdentitiesOnly yes
EOF
 
# Add public key to GitHub repo as Deploy Key
cat ~/.ssh/github_repo_name.pub
# Go to repo → Settings → Deploy keys → Add
# Check "Allow write access"

Important Files

Content Structure

content/
├── index.md          # Homepage (REQUIRED!)
├── CLAUDE.md         # Instructions for Claude
├── incoming/         # Uploaded files
└── ...               # Your notes

Important: You MUST have content/index.md or you’ll get 404 on homepage!

index.md Example

---
title: Welcome
---
 
# Welcome to my digital garden
 
This is the homepage.
 
## Recent notes
- [[Note 1]]
- [[Note 2]]

Updating Quartz

# Fetch upstream changes
git fetch upstream
git merge upstream/v4
 
# Resolve conflicts if any
# Re-apply local fixes (like the autostash fix)