quartz

created 2 min read

quartz is the static site engine that turns my obsidian vault into the public chaos garden.

it is both the garden hose and the sprinkler system: mostly invisible when working, deeply annoying when clogged.

🧭 what quartz does

  • converts markdown notes into web pages
  • builds the site from my obsidian vault
  • handles links, backlinks, tags, graph view, explorer, and layout
  • lets the garden stay markdown-first
  • gives me a customizable site without needing wordpress for this project

🧩 why i use it

  • i can write in obsidian
  • i can keep notes connected with wiki links
  • i can organize things gradually instead of perfectly
  • i can publish without manually making every page
  • it lets the site feel like a living map instead of a normal blog

🛠️ important pieces

  • quartz.config.ts controls site behavior
  • quartz.layout.ts controls page layout
  • quartz/styles/custom.scss controls custom styling
  • content/ points to the obsidian vault
  • deploy.sh sends the built site to the server

🌿 how it fits the garden

quartz is not the garden itself.

the garden is the notes, maps, patterns, links, scraps, weird thoughts, and little explanatory trails.

quartz is the machine that grows those notes into a website.

🧱 current setup notes

  • obsidian is the writing space
  • quartz is the publishing system
  • the garden uses lowercase filenames and kebab-case
  • titles can be prettier inside the notes
  • maps are used for navigation
  • archive pages are used for collections
  • backlinks help pages find each other naturally

⚠️ things that can break

  • explorer sorting
  • graph display
  • sidebars and scroll behavior
  • config syntax
  • build errors
  • deploy scripts
  • broken links
  • weird casing in titles or folders
  • plugins/components not existing in the installed quartz version

🧰 useful checks

when something breaks, check:

  • did the site build successfully?
  • did the deploy finish?
  • did i save the note?
  • is the filename web-safe?
  • is the frontmatter valid?
  • did i edit the right quartz file?
  • did i accidentally break a bracket, comma, or import?
  • is the browser showing an old cached version?

🔗 related notes

Graph View

Backlinks