Overview
Quartz reads the markdown Obsidian writes, with no conversion step, provided the vault matches what Quartz expects. This page lists the mismatches that bite: frontmatter keys Quartz ignores, link resolution on duplicate filenames, patterns that publish private files, and Obsidian aliases that become redirects. Claims were checked against Quartz 4.5.2 source. Layout is in obsidian.
Make the vault the content/ directory
Quartz builds from content/ (the -d flag changes it). Either make the vault root that folder, or link a vault into a Quartz checkout. npx quartz create offers new, copy, and symlink strategies for this.
ln -s ~/notes ~/site/content # edits appear in the repo immediately
rsync -av ~/notes/ ~/site/content/ # one-way copy; needs re-runningUse the symlink for active authoring and commit through git or Obsidian Git.
Know which frontmatter keys Quartz reads
| Quartz reads | Quartz does not read |
|---|---|
title, tags, aliases, permalink, cssclasses | slug (the output path comes from the file path) |
description (the meta description) | summary (stock Quartz; see the next paragraph) |
created or date; modified, lastmod, updated, or last-modified; published or publishDate | last_updated |
draft: true (with RemoveDrafts) | status: draft |
FrontMatter has no key-alias option, so a summary field does not become the description. Without description, Quartz uses the first sentences of the body. Either write description, or customize the head component as this site does: its CustomHead falls back to summary for the meta description, while the social-image emitter still reads only description and the body text. Add modified if the displayed date should match your own date field; otherwise the date comes from the file’s last git commit (quartz-config).
Resolve wikilinks safely
Quartz resolves [[note]] by filename when exactly one page has it, as Obsidian does. When two pages share a filename, Quartz emits a root-relative link that 404s, and the build does not warn. Use [[folder/note]] for any slug that could collide, and add a link check to CI (this repo runs scripts/lint-links.mjs). Details are in quartz-debugging.
Keep vault-only files out with ignorePatterns
ignorePatterns: ["private", "daily", "_templates", "_attachments", "**/*.excalidraw.md", ".obsidian"],Patterns match from the content root, so private skips only a top-level folder; use **/private for nested ones. To publish a subset of daily notes, move them to a folder that is not ignored.
Check Obsidian aliases before publishing
Quartz turns every aliases entry into a redirect page at that slug. An alias such as MOC or Postgres creates /MOC or /Postgres as a redirect stub. Keep aliases for names you want as URLs; drop the rest, or the redirects pile up.
Use obsidian-export only for non-Quartz targets
obsidian-export is a Rust CLI, not a plugin. It rewrites wikilinks to relative markdown links and resolves embeds, which suits a generator without wikilink support.
cargo install obsidian-export
obsidian-export ~/notes ~/output --skip-tags privateDo not put it before a Quartz build: Quartz handles wikilinks natively, and conversion adds a step that can break relative links.
Deploy with a push
Edit in Obsidian, commit, and push to main; the Actions workflow runs npx quartz build and publishes. The workflow is in quartz-deployment and Pages settings are in github-pages.