Skip to main content
The build command transforms your Markdown content into a complete static website, with optional local development server and automatic rebuilding.

​
Basic Usage

npx quartz build [options]

​
Command Options

​
Output Options

​
--output
string
default:"public"
Output folder for generated static files.Alias: -o
npx quartz build --output ./dist
The build process generates a complete static site with HTML, CSS, JavaScript, and assets in this directory.

​
Development Server Options

​
--serve
boolean
default:"false"
Run a local HTTP server to preview your Quartz site.
npx quartz build --serve
Enabling --serve automatically enables --watch for a complete development experience.
The server provides:
  • Live preview at http://localhost:8080
  • Automatic page refresh on content changes
  • Proper MIME type handling for all assets
  • Smart URL redirects (e.g., /page → /page.html)
​
--port
number
default:"8080"
Port to serve your local Quartz site on.
npx quartz build --serve --port 3000
​
--wsPort
number
default:"3001"
WebSocket port for hot-reload notifications.
npx quartz build --serve --wsPort 3002
The WebSocket connection enables instant page updates when files change, without manual browser refresh.
​
--baseDir
string
default:""
Base path to serve your local server on (useful for subdirectory deployments).
npx quartz build --serve --baseDir /docs
Your site will be available at http://localhost:8080/docs
​
--remoteDevHost
string
default:""
URL override for WebSocket connection when not developing on localhost.
npx quartz build --serve --remoteDevHost wss://myserver.com
Useful for remote development environments or cloud IDEs.

​
Watch Options

​
--watch
boolean
default:"false"
Watch for file changes and rebuild automatically.
npx quartz build --watch
Monitors these file patterns:
  • **/*.ts - TypeScript source files
  • **/*.tsx - React components
  • **/*.scss - Stylesheets
  • quartz/cli/*.js - CLI scripts
  • quartz/static/**/* - Static assets
  • package.json - Dependencies

​
Performance Options

​
--concurrency
number
Number of threads to use for parsing notes.
npx quartz build --concurrency 4
By default, Quartz automatically determines optimal concurrency based on your CPU. Only set this if you need to limit resource usage.
​
--bundleInfo
boolean
default:"false"
Show detailed bundle information and analysis.
npx quartz build --bundleInfo
Displays:
  • Number of files transpiled
  • Bundle size in bytes
  • Detailed metafile analysis

​
Common Options

​
--directory
string
default:"content"
Directory containing your Markdown content files.Alias: -d
npx quartz build --directory ./my-notes
​
--verbose
boolean
default:"false"
Enable verbose logging for debugging.Alias: -v
npx quartz build --verbose

​
Examples

​
Production Build

Build your site for production deployment: 
npx quartz build
This generates optimized static files in the ./public directory.

​
Development Mode

Start a local development server with hot reload: 
npx quartz build --serve

​
Custom Output Directory

Build to a different output folder: 
npx quartz build --output ./dist

​
Watch Mode (No Server)

Rebuild on changes without starting a server: 
npx quartz build --watch

​
Debug Build

Get detailed information about the build process: 
npx quartz build --verbose --bundleInfo

​
Build Process

The build command performs these steps:
1

Configuration Loading

Reads quartz.config.ts to understand your site configuration, plugins, and transformers.
2

Source Transpilation

Compiles TypeScript and SCSS files using esbuild with optimizations:
  • Minifies whitespace and syntax
  • Bundles dependencies
  • Processes Sass/SCSS stylesheets
  • Transpiles JSX/TSX components
3

Content Processing

Transforms Markdown files through configured plugins:
  • Parses frontmatter
  • Processes wikilinks
  • Generates backlinks
  • Applies transformers
4

Static Generation

Generates HTML pages, assets, and resources:
  • Renders pages with layout
  • Copies static files
  • Generates search index
  • Creates graph data

​
Development Server

When using --serve, Quartz starts an HTTP server with these features:

​
Auto-Refresh

WebSocket-based hot reload automatically refreshes your browser when:
  • Content files change
  • Configuration is updated
  • Components are modified
  • Styles are edited

​
Smart Routing

The development server handles URL routing intelligently: 
# Trailing slash redirect
/page/ → /page.html

# Extension-less URLs
/page → /page.html

# Index files
/folder/ → /folder/index.html

​
MIME Types

Proper Content-Type headers for all file types:
  • .webp → image/webp
  • .avif → image/avif
  • Standard web formats handled automatically

​
Output Structure

The build generates this directory structure: 
public/
├── index.html              # Homepage
├── 404.html                # Error page
├── static/
│   ├── styles.css          # Compiled styles
│   └── ...                 # Other static assets
├── [your-pages].html       # Generated pages
└── ...                     # Additional resources

​
Performance Tips

For large sites:
  • Use --concurrency to optimize CPU usage
  • Enable --bundleInfo to identify large dependencies
  • Consider incremental builds with --watch during development

​
Troubleshooting

​
Build Failures

If the build fails:
  1. Check quartz.config.ts syntax
  2. Verify all plugins are properly configured
  3. Use --verbose for detailed error messages
  4. Ensure content directory exists and is readable

​
Server Issues

Change the port:
npx quartz build --serve --port 3000
Check if the WebSocket port is blocked:
npx quartz build --serve --wsPort 3002
Ensure baseDir starts with /:
npx quartz build --serve --baseDir /docs

​
Source Code Reference

The build command implementation can be found at:
  • quartz/bootstrap-cli.mjs:35 - Command definition
  • quartz/cli/handlers.js:235 - Build handler function
  • quartz/cli/args.js:61 - Argument definitions

​
Next Steps

Sync Command

Deploy your built site to GitHub

Configuration

Customize your build with quartz.config.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us