---
title: "Obsidian: Publishing to Quartz"
slug: "obsidian-publishing-to-quartz"
category: "tooling"
tags: ["tooling", "obsidian", "quartz", "publishing", "ssg", "wikilinks", "deploy"]
status: "stable"
last_updated: 2026-05-14
summary: "Publish an Obsidian vault to a Quartz 4 static site: same markdown and wikilinks, frontmatter alignment, obsidian-export caveats, and deploy flow."
related: ["[[tooling/obsidian]]", "[[tooling/obsidian-vault-structure]]", "[[tooling/obsidian-templates]]", "[[tooling/quartz]]", "[[tooling/quartz-deployment]]", "[[ops/github-pages]]"]
---

## 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 [[tooling/quartz]] for the Quartz-side configuration and [[tooling/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:

```bash
# 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:

```yaml
---
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`:

```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.

## Wikilinks resolve without modification

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:

```bash
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:

```ts
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:

```bash
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 [[tooling/quartz-deployment]] for the full Actions workflow and [[ops/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.

## Related

- [[tooling/obsidian]]
- [[tooling/obsidian-vault-structure]]
- [[tooling/obsidian-templates]]
- [[tooling/obsidian-plugins]]
- [[tooling/quartz]]
- [[tooling/quartz-deployment]]
- [[ops/github-pages]]