This guide walks you through setting up Quartz from scratch. If you already ran the quickstart on the home page, you can skip ahead to whichever step you’re on.
Prerequisites
You need these tools installed before continuing:
- Node.js v22 or later (run
node -vto check) - npm v10.9.2 or later (bundled with Node — run
npm -vto check) - Git (run
git -vto check)
Common issues
- Linux: System packages (
apt install nodejs) often ship much older versions. Use nvm or the NodeSource repository to get Node.js v22. - Windows: When installing Git, make sure “Git from the command line and also from 3rd-party software” is selected so that
gitis available in your terminal. Ifnode -vorgit -vshows “command not found”, restart your terminal or check your PATH. - macOS: The Xcode command-line tools include Git (
xcode-select --install). For Node.js, nvm or the official installer both work.
Using Bun
Quartz runs on Node.js, but you can install its dependencies with Bun (bun install). Bun does not link a package’s own commands the way npm does, so bunx quartz fails with “could not determine executable to run”. Use bun run quartz instead, followed by the command, wherever these docs say npx quartz: bun run quartz create, bun run quartz build --serve.
Setup Steps
Follow these in order:
- Installation — Get Quartz (via GitHub template or clone), install dependencies, run the setup wizard (
npx quartz create, which also installs plugins), and preview your site locally - Authoring Content — Write and organize your Markdown notes in the
content/folder - Push to GitHub — Create a repository and push your site with
npx quartz sync - Deploy — Host your site for free on GitHub Pages, Cloudflare, Netlify, or Vercel
Upgrading & Migrating
- What's New in Quartz 5 — Overview of new features and changes
- Upgrading Quartz — Keep your Quartz installation up to date
- Migrating to Quartz 5 — Migrate from Quartz 4 or Quartz 3