PKM

Quartz PKM Site Setup

3 min read

Quartz PKM Site Setup

Turn an Obsidian-style markdown vault (with [[wiki-links]]) into a browsable static site using Quartz — a Hugo-based framework pre-configured for PKM/digital gardens.

Why / When to Use

Hugo core does not parse [[wiki-links]] natively, and the Hugo maintainers have officially declared they will not add it. Quartz is Hugo under the hood but pre-wires wiki-links, backlinks panel, graph view, and tag pages out of the box. Use Quartz whenever your vault uses wiki-link syntax extensively.

Core Concept

Quartz = Hugo + PKM layer already configured. You are not giving anything up by choosing Quartz over bare Hugo; you gain the PKM layer for free.

Feature comparison:

FeatureBare HugoQuartz
[[wiki-links]]❌ (needs hack)✅
Backlinks panel❌✅
Graph view❌✅
Tag / type taxonomies✅✅
Live reload (hugo server)✅✅
Custom themes✅✅

Installation (Node.js required)

npx quartz create

Follow the prompts; point content directory at your vault.

Docker Setup (Recommended — no Node.js needed)

Two options:

Option A — Official Quartz Docker (local preview only)

# Run from inside your Quartz folder
docker run --rm -itp 8080:8080 -p 3001:3001 \
  -v ./content:/usr/src/app/content \
  $(docker build -q .)

Browse to http://localhost:8080. No persistence — for quick preview only.

Option B — dockerized-quartz (self-hosted, auto-rebuild)

Best for daily use: mounts vault as read-only volume, rebuilds after note changes, serves via NGINX.

# docker-compose.yml
version: '3.8'
services:
  quartz:
    image: shommey/dockerized-quartz
    container_name: pkm-quartz
    environment:
      AUTO_REBUILD: true
      BUILD_UPDATE_DELAY: 300    # rebuild 5 min after last note change
    volumes:
      - D:\OneDrive\Personal\Notes:/vault:ro
    ports:
      - "8080:80"
    restart: unless-stopped
docker-compose up -d

Browse to http://localhost:8080. Notes saved anywhere in OneDrive appear in the site within 5 minutes.

Key Options / Variants

  • BUILD_UPDATE_DELAY: 300 — seconds to wait after a change before rebuilding (debounce for frequent saves)
  • :ro volume flag — vault is read-only inside the container; Quartz cannot modify your notes
  • Basic auth — shommey/dockerized-quartz supports optional password protection for LAN access

Gotchas

  • Quartz requires Node.js for the npx quartz create setup step; the Docker image removes this requirement
  • Your existing frontmatter (title, date, tags, type) is read natively — no changes needed
  • Your maps/ folder works as Quartz content sections; the graph view connects them automatically
  • [[wiki-links]] must match filenames exactly (case-sensitive on Linux containers)

Source

Conversation “Hugo setup for markdown presentations” — 2026-05-13

Updates — 2026-05-13

Docker Compose environment YAML Syntax Fix

Docker Compose environment accepts two valid formats — mixing them causes a parse error:

Wrong (mixed list/mapping):

environment:
  AUTO_REBUILD: true
  - BUILD_UPDATE_DELAY=300   # ← mixing formats = error

Option A — Mapping format (recommended):

environment:
  AUTO_REBUILD: "true"
  BUILD_UPDATE_DELAY: "300"

Option B — List format:

environment:
  - AUTO_REBUILD=true
  - BUILD_UPDATE_DELAY=300

Validate before starting: docker-compose config — prints the resolved file without running anything. If it prints cleanly, the YAML is valid.

Graph View