LLM Best Practices

Obsidian: Publishing to Quartz

4 min read

View markdown source

Overview

Quartz 4 reads the same markdown that Obsidian writes. No conversion step is required when the vault is structured correctly. This page covers what “structured correctly” means in practice: frontmatter alignment, wikilink resolution, the ignorePatterns configuration, and the deploy flow from vault to published site. See quartz for the Quartz-side configuration and quartz-deployment for the GitHub Actions workflow.

The vault is the content directory

Quartz’s content/ directory is the source of truth for the published site. Point it at your vault root, or make your vault root the content/ folder inside the Quartz repo. Either way, the same files serve both tools.

The Quartz quartz.config.ts file at the repo root points to content/ as the content root. If your vault is at ~/notes/ and your Quartz repo is at ~/site/, symlink or copy:

# Option 1: symlink (vault edits are immediately in the repo)
ln -s ~/notes ~/site/content
 
# Option 2: copy (one-way, requires sync)
rsync -av ~/notes/ ~/site/content/

Option 1 is cleaner for active authoring. The vault and the site repo are one filesystem path. Commit through the CLI or Obsidian Git.

Align frontmatter with Quartz’s expected fields

Quartz reads the title, tags, date (or last_updated), and description (or summary) fields from frontmatter. Map your vault schema to these:

---
title: "Postgres: Best Practices"
slug: "postgres"
tags: ["backend", "postgres"]
last_updated: 2026-05-14   # Quartz reads as page date
summary: "..."             # Quartz uses as meta description
---

If you use summary instead of description, add a field alias in quartz.config.ts:

Plugin.FrontMatter({
  aliases: { description: ["summary"] }
})

Without this alias, Quartz uses the first paragraph as the meta description, which may be a rule statement rather than a summary sentence.

Quartz 4 resolves [[wikilinks]] using the same algorithm as Obsidian: by slug first, by path when a slug is ambiguous. No conversion is needed.

The one caveat: Quartz resolves wikilinks at build time. If a wikilink points to a note that does not exist in content/, Quartz generates a broken link (or, with the default configuration, a styled dead link). Run npx quartz build locally to catch broken links before pushing:

npx quartz build 2>&1 | grep -i "broken\|not found\|dead link"

Prefer [[folder/slug]] over [[slug]] for notes whose slug might collide with future notes in other folders.

Configure ignorePatterns to keep vault-only files out of the site

In quartz.config.ts, the ignorePatterns array lists globs of files and folders to exclude from the build:

ignorePatterns: [
  "private",
  "daily",
  "_templates",
  "_attachments",
  "*.excalidraw.md",
  ".obsidian"
],

This prevents daily notes, templates, private folders, and Obsidian workspace files from publishing. The .obsidian folder contains plugin settings and workspace state; it should never publish.

If you want to publish a subset of daily notes (weekly reviews, for example), move them to a dedicated folder (weekly/) that is not in ignorePatterns.

Use obsidian-export for a one-time migration or external consumers

obsidian-export (the Rust CLI, not a plugin) converts an Obsidian vault to standard markdown: it expands wikilinks to relative markdown links, resolves transclusions, and strips Obsidian-specific syntax.

Use it when:

  • You are migrating the vault to a site generator that does not support wikilinks natively.
  • You want to share a rendered subset of the vault with a tool that reads standard markdown.

Do not use it as part of the Quartz build. Quartz handles wikilinks natively. Running obsidian-export first introduces a conversion step that can break relative links and requires re-running on every vault change.

Install: cargo install obsidian-export (requires Rust). Usage:

obsidian-export ~/notes ~/output --skip-tags private

--skip-tags private excludes any note with a private tag. Add this flag when exporting a subset for external use.

Deploy with git push, not manual copy

The standard workflow:

  1. Edit notes in Obsidian.
  2. Commit with git commit -m "..." (CLI or Obsidian Git plugin).
  3. Push to main.
  4. GitHub Actions runs npx quartz build and deploys to GitHub Pages.

See quartz-deployment for the full Actions workflow and github-pages for GitHub Pages configuration. The deploy takes 60 to 90 seconds on a typical vault. The Quartz build step catches frontmatter errors and broken wikilinks before the site updates.

Graph View

Backlinks