---
publish: true
permalink: /sh/garden/quartz
title: Quartz
created: 2026-02-05T09:58:59.615-07:00
modified: 2026-02-05T12:21:13.918-07:00
tags:
  - self_hosting
  - digital_gardening
  - static_site
cssclasses: ""
---

Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Perfect for publishing [[20-29 HOBBYS/22 SELF HOSTING/22.11 DIGITAL GARDEN/Obsidian]] vaults as digital gardens.

## Features

- **Obsidian compatibility** — Wikilinks, callouts, backlinks
- **Full-text search** — Client-side search
- **Graph view** — Interactive note connections
- **Popover previews** — Hover to preview linked notes
- **Fast** — SPA routing, tiny bundles
- **Customizable** — JSX components, plugin system

## Installation

Requires Node.js v22+.

```bash
git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create
```

Follow the prompts to initialize with your content.

## Configuration

Main config: `quartz.config.ts`

```typescript
const config: QuartzConfig = {
  configuration: {
    pageTitle: "My Digital Garden",
    enableSPA: true,
    enablePopovers: true,
    analytics: null,  // or plausible, umami, etc.
    locale: "en-US",
    baseUrl: "garden.example.com",
    ignorePatterns: ["private", ".obsidian"],
    defaultDateType: "modified",
    theme: {
      cdnCaching: true,
      typography: {
        header: "Schibsted Grotesk",
        body: "Source Sans Pro",
        code: "IBM Plex Mono",
      },
      colors: {
        lightMode: { /* ... */ },
        darkMode: { /* ... */ },
      },
    },
  },
  plugins: { /* ... */ },
}
```

## Content

All content lives in `/content` folder. Home page is `content/index.md`.

### Frontmatter

```yaml
---
title: My Note
description: A description for previews
tags:
  - example
draft: false      # true = don't publish
publish: true     # used by Quartz Syncer
date: 2026-02-05
---
```

### Supported Syntax

- Standard Markdown + GFM (tables, footnotes, task lists)
- Obsidian wikilinks: `[[Note Name]]`
- Obsidian callouts: `> [!info]`
- LaTeX math: `$inline$` and `$$block$$`
- Syntax highlighting

## Building

```bash
# Development (hot reload)
npx quartz build --serve

# Production build
npx quartz build

# Output goes to /public
```

## Syncing Content

### Manual

```bash
npx quartz sync
```

### Quartz Syncer Plugin (Recommended)

Install the **Quartz Syncer** plugin in [[20-29 HOBBYS/22 SELF HOSTING/22.11 DIGITAL GARDEN/Obsidian]]:

1. Install from Community Plugins
2. Configure Git provider (GitHub, GitLab, etc.)
3. Set Quartz repo path
4. Use plugin to selectively publish notes

Features:
- Compiles Dataview queries to static content
- Diff viewer before publishing
- Selective publish/update/remove
- Smart caching

## Hosting Options

### Self-hosted with [[20-29 HOBBYS/22 SELF HOSTING/22.11 DIGITAL GARDEN/Caddy]]

Build locally or via CI, serve `/public` with Caddy.

### GitHub Pages

Add `.github/workflows/deploy.yml`:
```yaml
name: Deploy Quartz
on:
  push:
    branches: [v4]
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx quartz build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: public
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4
```

### Cloudflare Pages

- Build command: `npx quartz build`
- Output directory: `public`
- Production branch: `v4`

## Resources

- Docs: https://quartz.jzhao.xyz/
- GitHub: https://github.com/jackyzha0/quartz
- Quartz Syncer: https://github.com/saberzero1/quartz-syncer