Flouda Vault

8 min read

Complete Guide to Quartz4 Static Site Generator

Quartz4 is a powerful static site generator specifically designed to transform Obsidian vaults into beautiful, interactive websites. This guide covers everything from initial setup to advanced containerization workflows, making it perfect for developers who want to publish their knowledge bases or documentation sites.

What is Quartz4?

Quartz4 is a fast, batteries-included static site generator that transforms your Obsidian vault into a fully functional website. It preserves your wiki-style links, supports themes, and provides real-time development features. Unlike traditional static site generators, Quartz4 is specifically optimized for knowledge management systems and interconnected content.

Getting Started with Quartz4

Prerequisites

Before starting, ensure you have:

  • Node.js version 18 or higher
  • npm or yarn package manager
  • Git for version control
  • An Obsidian vault or markdown content to publish

Initial Setup

To create your first Quartz4 project:

# Clone the official Quartz repository
git clone https://github.com/jackyzha0/quartz.git
cd quartz
 
# Install dependencies
npm ci
 
# Install a theme (optional but recommended)
curl -s -S https://raw.githubusercontent.com/saberzero1/quartz-themes/master/action.sh | bash -s -- obsidian-gruvbox
 
# Initialize your Quartz project
npx quartz create

The npx quartz create command will guide you through setting up your content directory and basic configuration. This interactive setup helps you connect your Obsidian vault to the Quartz build system.

Theme Installation

Quartz4 supports various themes to customize your site’s appearance. The example above installs the obsidian-gruvbox theme, which provides a dark, modern look popular among developers. You can explore additional themes at the quartz-themes repository.

Development Workflow

Local Development Server

For continuous development and testing, use the following command:

npx quartz build --serve --watch --concurrency 6

This command performs several important functions:

  • Build: Generates the static site from your markdown files
  • Serve: Starts a local development server
  • Watch: Monitors file changes and rebuilds automatically
  • Concurrency: Processes multiple files simultaneously for faster builds

Development Ports

The development server uses two ports:

  • Port 8080: Main website serving port - access your site at http://localhost:8080
  • Port 3001: WebSocket port for live reload functionality - automatically refreshes pages when content changes

These ports can be configured in your quartz.config.ts file if needed for your development environment.

Containerization with Docker

Why Containerize Quartz4?

Containerization provides several advantages:

  • Platform Independence: Run identical environments across Windows, macOS, and Linux
  • Dependency Isolation: Avoid conflicts with system Node.js versions
  • Reproducible Builds: Ensure consistent behavior across different machines
  • Easy Deployment: Simplified production deployment workflows

Basic Container Setup

Use the following command to run Quartz4 in a container:

nerdctl run --name quartz-testing \
  -p 8080:8080 \
  -p 3001:3001 \
  -it --rm \
  -v ${HOME}/repos/vault:/share/vault \
  -w /root \
  node:22 -- bash

This command:

  • Creates a container named quartz-testing
  • Maps both development ports to the host
  • Mounts your vault directory for live editing
  • Uses Node.js 22 as the base image
  • Provides an interactive bash shell

File Synchronization Solution

For Windows users or complex mounting scenarios, file synchronization ensures your container stays updated with local changes:

#!/bin/bash
SOURCE="/share/vault/"
DEST="/root/vault/"
 
# Initial sync
rsync -av --delete "$SOURCE" "$DEST"
 
# Poll every 5 seconds for changes
while true; do
    sleep 5
    rsync -av --delete \
      --exclude="quartz/.quartz-cache/" \
      --exclude="node_modules/" \
      --exclude="public" \
      "$SOURCE" "$DEST"
done

Setup Requirements:

  1. Install rsync in your container: apt update && apt install rsync -y
  2. Save the script as sync-vault.sh
  3. Make it executable: chmod +x sync-vault.sh
  4. Run it in the background: ./sync-vault.sh &

The script excludes build artifacts and dependencies to improve performance and avoid conflicts.

Container Development Workflow

Once your container is running with file synchronization:

  1. Initial Setup: Follow the get started steps within the container
  2. Development: Edit files on your host system using your preferred editor
  3. Live Updates: The sync script automatically copies changes to the container
  4. Testing: Access your site at http://localhost:8080 with live reload

For advanced container management and rootless setups, see our containerd setup guide.

Configuration and Customization

Basic Configuration

Quartz4 uses a quartz.config.ts file for configuration. Key settings include:

  • Content Directory: Where your markdown files are located
  • Output Directory: Where the built site is generated
  • Theme Settings: Customization options for your chosen theme
  • Plugin Configuration: Enable/disable features like search, graph view, etc.

Content Organization

Structure your content directory logically:

content/
├── index.md          # Homepage
├── posts/            # Blog posts
├── docs/             # Documentation
└── attachments/      # Images and files

Advanced Features

Quartz4 supports advanced features like:

  • Interactive Graph: Visual representation of content connections
  • Full-text Search: Built-in search functionality
  • Tag Support: Organize content with tags
  • Backlink Generation: Automatic discovery of content relationships

Production Deployment

Build for Production

Generate a production-ready build:

npx quartz build

This creates optimized static files in the public/ directory, ready for deployment to any static hosting service.

Deployment Options

Popular deployment targets include:

  • GitLab Pages: Integrated with GitLab repositories
  • GitHub Pages: Free hosting for open-source projects
  • Netlify: Advanced features and easy deployment
  • Vercel: Optimized for modern web frameworks

Troubleshooting Common Issues

Build Failures

Common build issues and solutions:

Node.js Version: Ensure you’re using Node.js 18 or higher

node --version
# Should be 18.x.x or higher

Memory Issues: Increase Node.js memory limit for large vaults

export NODE_OPTIONS="--max-old-space-size=4096"
npx quartz build

File Permissions: Ensure Quartz can read your content directory

chmod -R 755 /path/to/your/content

Container Issues

Port Conflicts: If ports 8080 or 3001 are in use, modify the container command

nerdctl run ... -p 8081:8080 -p 3002:3001 ...

Mount Problems: Verify your vault path is correct and accessible

ls -la ${HOME}/repos/vault
# Should show your vault contents

Best Practices

Content Management

  1. Consistent Naming: Use clear, descriptive filenames
  2. Link Maintenance: Regularly check for broken internal links
  3. Image Optimization: Compress images for faster loading
  4. Regular Backups: Keep your vault under version control

Development Workflow

  1. Version Control: Track changes to both content and configuration
  2. Automated Testing: Set up CI/CD pipelines for deployment
  3. Performance Monitoring: Regular audits of build times and site performance
  4. Documentation: Maintain clear documentation for your setup

Security Considerations

  1. Content Review: Ensure no sensitive information is included in public builds
  2. Access Control: Configure appropriate permissions for production deployments
  3. Updates: Keep Quartz4 and dependencies updated for security patches

Performance Optimization

Build Performance

  • Incremental Builds: Use --watch during development
  • Concurrency: Adjust the --concurrency flag based on your system
  • Cache Management: Clear .quartz-cache if experiencing issues

Site Performance

  • Image Optimization: Use appropriate image formats and sizes
  • Lazy Loading: Enable lazy loading for images and content
  • CDN Integration: Consider using a CDN for static assets

References and Resources

Official Documentation

Community Resources

  • Obsidian - The knowledge management app that works perfectly with Quartz4
  • Node.js - JavaScript runtime required for Quartz4

Questions Answered in This Document

Q: What is Quartz4 and why should I use it? A: Quartz4 is a static site generator specifically designed for Obsidian vaults that transforms your knowledge base into a beautiful, interactive website with features like graph views, search, and wiki-style linking.

Q: How do I set up Quartz4 for the first time? A: Clone the repository, install dependencies with npm ci, optionally install a theme, and run npx quartz create to initialize your project with your content directory.

Q: What ports does Quartz4 use during development? A: Quartz4 uses port 8080 for serving the website and port 3001 for WebSocket connections that enable live reload functionality.

Q: How can I run Quartz4 in a container? A: Use a Node.js container with volume mounts for your content, expose ports 8080 and 3001, and optionally set up file synchronization for seamless development.

Q: What’s the command to start the development server? A: Use npx quartz build --serve --watch --concurrency 6 to build, serve, and watch for changes with optimized performance.

Q: How do I handle file synchronization in containers? A: Use rsync to synchronize your host vault directory with the container, excluding build artifacts and dependencies for optimal performance.

Q: What are the system requirements for Quartz4? A: You need Node.js 18 or higher, npm or yarn, Git, and a markdown-based content directory or Obsidian vault.

Q: How do I deploy Quartz4 to production? A: Run npx quartz build to generate static files in the public/ directory, then deploy to any static hosting service like GitLab Pages, GitHub Pages, or Netlify.

Q: What should I do if I encounter build failures? A: Check your Node.js version (should be 18+), increase memory limits for large vaults, verify file permissions, and clear the .quartz-cache directory if needed.

Q: Can I customize the appearance of my Quartz4 site? A: Yes, you can install themes from the quartz-themes repository or customize the appearance through the quartz.config.ts file and custom CSS.

Q: What development tools work well with Quartz4? A: Quartz4 works well with any markdown editor, but modern editors like Neovim with proper configuration provide excellent support for wiki-style linking and live preview. Version control with Git and containerized development environments are also recommended.

Graph View

Backlinks