Installation

1. Get Quartz

option_a_template_recommended:

• create_repository: Quartz repository → Use this template → Create a new repository.
• clone_enter:

git clone https://github.com/<your-username>/<your-repo>.git
cd <your-repo>

option_b_clone_directly:

• clone_enter:

git clone https://github.com/jackyzha0/quartz.git
cd quartz

• note: Requires pointing `origin` remote to your repository later.

2. Install Dependencies

requirements:

• Node.js 22+ (node -v)

install:

npm i

notes:

• Subsequent clones: use npm ci.

3. Initialize Your Site

create:

npx quartz create

prompts:

• template:
  • default
  • obsidian
  • ttrpg
  • blog
  • details: create > Templates
• content_strategy:
  • new: empty content/
  • copy: copy existing content
  • symlink: link existing content
• base_url:
  • Deployment URL without https://
  • example: mysite.github.io/quartz
• link_resolution:
  • shortest
  • absolute
  • relative
  • skipped_for: Obsidian/TTRPG
• reference: `quartz create` CLI reference

4. Install Plugins

install_from_config:

npx quartz plugin install --from-config

effects:

• Downloads/builds plugins declared in quartz.config.yaml to .quartz/plugins/.

build_failure_recovery:

npx quartz plugin install --latest

reference:

• troubleshooting > Plugins fail to build on a fresh clone

5. Preview Site

serve:

npx quartz build --serve

runtime:

• URL: http://localhost:8080
• auto_reload: enabled
• content_root: content/
• authoring: Authoring Content

---

Setting Up Your GitHub Repository

skip:

• If Option A created your repository, go to Push Your Site.

Create the Repository

steps:

• Create repository: GitHub.com
• Do not initialize with README, license, or .gitignore.
• Copy repository URL.

Connect Your Local Clone

set_origin:

git remote -v
git remote set-url origin REMOTE-URL

notes:

• Quartz auto-configures upstream for npx quartz upgrade.

Push Your Site

first_push:

npx quartz sync --no-pull

subsequent_updates:

npx quartz sync

npx quartz sync Options

options:

• -d, --directory: content folder; default: content
• -v, --verbose: extra logging
• --commit, --no-commit: toggle automatic git commit
• --push, --no-push: toggle push to GitHub fork
• --pull, --no-pull: toggle pull from GitHub fork before push

Next Steps

links:

• Authoring Content
• Hosting: GitHub Pages, Cloudflare, Netlify, Vercel
• Configuration