Skip to main content

​
Create Your First Quartz Site

Once you have Quartz installed, you can create and build your first site in just a few commands.
1

Initialize Your Content

Run the create command to set up your content folder:
npx quartz create
This interactive command will guide you through the setup process.

​
Setup Options

You’ll be prompted to choose how to initialize your content:
Start with a blank slate:
  • Creates a new content folder
  • Adds a default index.md welcome page
  • Perfect for starting fresh
---
title: Welcome to Quartz
---

This is a blank Quartz installation.
See the [documentation](https://quartz.jzhao.xyz) for how to get started.
Next, choose how Quartz should resolve links (this should match your Obsidian settings):
StrategyDescriptionExample
Shortest PathLinks use the shortest unique path (default)[[note]]
Absolute PathLinks use full path from root[[folder/subfolder/note]]
Relative PathLinks are relative to current file[[../other/note]]
You can change this later in quartz.config.ts by modifying the markdownLinkResolution option.
2

Build Your Site

Build your Quartz site into static HTML files:
npx quartz build
This command:
  • Processes all Markdown files in your content folder
  • Generates static HTML, CSS, and JavaScript
  • Outputs to the public folder (by default)

​
Build Options

npx quartz build
3

Preview Locally

Start a local development server to preview your site:
npx quartz build --serve
This will:
  • Build your site
  • Start a local server at http://localhost:8080
  • Watch for changes and rebuild automatically
  • Enable hot-reload for instant updates

Local Preview

Open http://localhost:8080 in your browser to see your site.

​
Server Options

npx quartz build --serve
The --serve flag automatically enables --watch mode, so your site will rebuild when you make changes.
4

Add Your Content

Add Markdown files to your content folder:
# Create a new note
echo "# My First Note\n\nThis is my first note in Quartz!" > content/first-note.md
Your site will automatically rebuild and refresh if the server is running.

​
Frontmatter

Add YAML frontmatter to customize each page:
---
title: My Custom Title
description: A brief description of this page
tags:
  - tutorial
  - getting-started
---

# Page Content

Your content here...

​
All CLI Commands

Quartz provides several commands to manage your site:

create

Initialize Quartz and set up your content folder
npx quartz create

build

Build Quartz into static HTML files
npx quartz build

update

Get the latest Quartz updates from upstream
npx quartz update

sync

Sync your Quartz to and from GitHub
npx quartz sync

restore

Restore your content folder from cache
npx quartz restore

​
Common Command Options

​
Build Command Flags

FlagAliasDefaultDescription
--serve-falseRun a local server for live preview
--watch-falseWatch for changes and rebuild automatically
--output-opublicOutput folder for built files
--directory-dcontentDirectory to look for content files
--port-8080Port to serve Quartz on
--wsPort-3001Port for WebSocket hot-reload
--verbose-vfalsePrint extra logging information
--bundleInfo-falseShow detailed bundle information
--concurrency-autoNumber of threads for parsing notes

​
Create Command Flags

FlagAliasDescription
--strategy-XContent folder setup strategy: new, copy, or symlink
--source-sSource directory to copy/symlink from
--links-lLink resolution strategy: absolute, shortest, or relative
--directory-dDirectory to create/modify (default: content)

​
Sync Command Flags

FlagAliasDefaultDescription
--commit-trueCreate a git commit for unsaved changes
--message-mautoOverride the default commit message
--push-truePush updates to your fork
--pull-truePull updates from your fork

​
Example Workflows

# Start development server
npx quartz build --serve

# Edit your notes in content/
# Site rebuilds automatically

# Stop server with Ctrl+C

# Initialize with symlink to Obsidian vault
npx quartz create --strategy symlink --source ~/Documents/ObsidianVault

# Build and preview
npx quartz build --serve

# Build for production
npx quartz build

# Commit and push changes
npx quartz sync

# Your hosting provider will pick up changes automatically

# Get latest updates from upstream
npx quartz update

# Rebuild your site
npx quartz build

​
Next Steps

Configuration

Customize your Quartz site by editing quartz.config.ts

Hosting

Deploy your site to the web using platforms like GitHub Pages, Netlify, or Vercel

Plugins

Extend Quartz functionality with plugins and transformers

Themes

Customize the look and feel of your site with themes and styling
For more advanced configuration and customization options, visit the official Quartz documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us