Quartz Syncer

Quartz Syncer is an Obsidian plugin for managing and publishing notes to Quartz, the fast, batteries-included static-site generator that transforms Markdown content into fully functional websites.

Features

• Background processing: Precompiles changes on vault updates so publishing is instant.
• Zero-config onboarding wizard: Guided GitHub setup for first-time publishing.
• Auto-publish timer: Schedule background publishing (desktop only).
• Secure tokens: Encrypted storage via electron.safeStorage (desktop).
• Diff viewer: Preview exact changes before publishing with split (side-by-side) or unified view.
• CLI support: Automate publishing workflows from the terminal with 12 commands.

Requirements

• Obsidian v1.13.0 or later
• Quartz v5 for full functionality

Quartz v4 support

Publishing notes and media to a Quartz v4 repository is supported and continues to work. Quartz site management — configuration editing, plugin management, and upgrades — requires Quartz v5 and is disabled when a v4 repository is detected.

Two rendering differences are worth knowing if you stay on v4:

• Custom task characters such as - [/], - [?], and - [!] are a Quartz v5 feature. Quartz Syncer publishes them unchanged, so v4 renders them literally rather than as styled tasks.
• URL casing differs between versions. Quartz v4 preserves the original casing of file and folder names, while v5 lowercases and hyphenates generated URLs. This affects how existing links resolve if you migrate.

Installation

Install the plugin from the Obsidian Community plugins browser.

Manual install: download the latest release from the Release Tab and copy it into your vault at .obsidian/plugins/quartz-syncer.

Alternatively, install through the Obsidian42 Brat plugin.

Setup

Tip

Quartz Syncer documentation

For the most up-to-date information on Quartz Syncer, please refer to the official documentation.

New to Quartz Syncer? Please follow the setup guide to get started.

Usage

Unsure on how to use Quartz Syncer, or just curious about its usage? Check the usage guide.

Advanced usage

For more advanced usages of Quartz Syncer, check the guides section.

CLI

Quartz Syncer supports the Obsidian CLI (v1.13+) for automating publishing workflows from the terminal. Obsidian must be running for CLI commands to work.

Commands

Command	Description	Example
quartz-syncer	Show available commands and usage	obsidian quartz-syncer
quartz-syncer:status	Show publish status of all marked notes	obsidian quartz-syncer:status format=json
quartz-syncer:sync	Publish pending notes and delete removed notes	obsidian quartz-syncer:sync force
quartz-syncer:publish	Publish pending notes only (no deletions)	obsidian quartz-syncer:publish
quartz-syncer:delete	Delete removed notes, or explicitly unpublish selected notes	obsidian quartz-syncer:delete action=unpublish path="notes/post.md" force dry-run
quartz-syncer:mark	Set/unset/toggle publish flag on notes	obsidian quartz-syncer:mark path="notes/post.md"
quartz-syncer:test	Test Git connection and credentials	obsidian quartz-syncer:test
quartz-syncer:cache	Manage the plugin cache	obsidian quartz-syncer:cache action=status
quartz-syncer:config	Read or write plugin settings	obsidian quartz-syncer:config action=get key=git.branch
quartz-syncer:upgrade	Pull upstream Quartz changes	obsidian quartz-syncer:upgrade force
quartz-syncer:version	Show plugin, Obsidian, and Quartz versions	obsidian quartz-syncer:version
quartz-syncer:plugin	Manage Quartz v5 plugins	obsidian quartz-syncer:plugin action=updates
quartz-syncer:quartz-config	Read or update Quartz v5 site config	obsidian quartz-syncer:quartz-config action=get key=pageTitle

The config and quartz-config commands default to listing all settings when no action is provided.

Common flags

• format=json — Return machine-readable JSON output (default: human-readable text).
• dry-run — Preview what would happen without making changes.
• force — Required for destructive operations (delete, upgrade, and the delete phase of sync).
• verbose — Enable detailed output (file paths, connection details).
• help — Show command-specific help and available flags.

Path patterns

The mark command and delete action=unpublish support three path resolution modes:

• Exact: path="notes/my-post.md" — Match a single file.
• Glob: path="notes/**/*.md" — Match files using glob patterns.
• Fuzzy: path="~my post" — Fuzzy search by name (prefix with ~).

Use dry-run to preview matched files before modifying: obsidian quartz-syncer:mark path="blog/**/*.md" dry-run

Unpublishing notes

delete force still deletes only notes removed from the vault. To remove a currently published note from the selected publishing destination while keeping the vault note, explicitly use action=unpublish and a required path:

obsidian quartz-syncer:delete action=unpublish path="notes/post.md" force dry-run format=json
obsidian quartz-syncer:delete action=unpublish path="notes/post.md" force verbose

force is required even for dry-run. Dry-run lists every matched note without deleting anything. Only currently published (in-sync) notes are eligible; no matches returns an error. Glob/fuzzy execution is blocked if it matches more than 80% of published notes when there are more than five. Dry-run still lists those matches with a warning; narrow the pattern or use exact paths. Supplying path without action=unpublish is rejected rather than falling back to bulk deletion.

Agents can use the separate operability action with an explicit, non-empty list of exact vault paths:

await window.__QS__.act({
	name: "pub.unpublish",
	params: { paths: ["notes/post.md"], confirm: true },
});

confirm: true is mandatory. Every path must match a currently published note or the whole request is rejected; duplicates are removed. No glob expansion occurs in the facade. pub.delete remains deleted-only. Unpublishing does not change frontmatter: notes remain publishable and can be published again (including by auto-publish, if enabled). Existing orphan-media auto-cleanup settings still apply to execution, but never to dry-run.

Example workflow

# Check what needs publishing
obsidian quartz-syncer:status

# Publish all pending notes (additive, no force needed)
obsidian quartz-syncer:publish

# Full sync including deletions
obsidian quartz-syncer:sync force

Troubleshooting

Important

Quartz-related questions

For issues or questions related to Quartz, not Quartz Syncer, please consult the Quartz documentation or reach out through the communication channels provided there.

If you need help with Quartz Syncer, or if you have a question, please first check the troubleshooting section. If your question or issue is not listed, feel free to reach out for help.

Disclosures

As per the Obsidian developer policies:

• Account requirements: Quartz Syncer needs to access your Quartz repository on a Git provider in order to publish your notes. An account on your chosen Git provider (GitHub, GitLab, Bitbucket, etc.) is required.
• Network use: Quartz Syncer accesses the network to manage and publish your notes to your Quartz repository. Quartz Syncer uses Git over HTTPS to communicate with your repository.
• Accessing files outside of Obsidian vaults: Quartz Syncer only manages explicitly marked and user-selected notes in your Quartz repository content folder. Quartz Syncer also fetches the current contents of this folder to compare changes against your notes. Quartz Syncer doesn't write any notes to your Obsidian vault, Quartz Syncer only writes to your Quartz repository (one-way only: from Obsidian vault to Quartz repository.)
• Secure storage: On desktop, access tokens are stored using electron.safeStorage encryption.

Acknowledgements

Quartz Syncer would not have been built without the following:

• Obsidian Digital Garden, on top of which most of this plugin was initially built.
• Quartz, for the amazing and welcoming community. Come say hi in the Discord server sometimes.
• Isomorphic-git, for enabling Git operations directly in JavaScript.
• Obsidian Linter, for inspiring the tabbed settings UI.
• Dataview, for their great API integration, allowing me to properly integrate it in Quartz.
• Datacore, for their wonderful integration despite its infancy, allowing easy integration into Quartz.
• Fantasy Statblocks, for their extensible functionality and easy-to-integrate API.
• Obsidian Publish, for inspiring me to create a similar solution for Quartz.
• The entire Obsidian community, for all your weird and amazing creations. Keep it up.