shahroz's notes

Quartz

  • Published
  • Last Updated
  • 5 min read

I am planning to use Quartz for publishing brain dump, random notes, unpolished thoughts or in short maintaining a Digital Garden. For a more polished and maintained technical blog, you can read in Quarto what I am currently using.

What Is Quartz?

Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites.

flowchart LR
    A["Obsidian<br/><sub>Markdown Editor</sub>"]
    B["Quartz<br/><sub>Converts Markdown to a bundle of HTML, JS, and CSS files (a website!)</sub>"]
    C["Cloudflare Pages<br/><sub>Hosting</sub>"]

    A --> B --> C

My Workflow

I mainly intend to use single Obsidian vault for editing and storing both private and public notes (I am not sure if it is the best way to do it or not but I will improve as I learn more).

Quartz Codebase

  1. Just followed the instructions on getting started with Quartz(cloning, installing dependencies, initializing quartz).
  2. I then, followed these instructions to set my own remote GitHub repo quartz (v4 is the main / production branch).
  3. I also created a Justfile to add the lengthy command (ugh, my precious fingers) like:
build:
	npx quartz build --serve        # for local build preview
 
update:
	npx quartz update               # for pulling updates from Quartz official repo
 
sync:
	npx quartz sync                 # for pushing local changes to your own Quartz repo

By now, Quartz code and content (public notes I want to share with the public) will stay in my own GitHub repo.

TODOs

  • Add some GitHub rule to now allow any commits and direct pushes to v4 or main / production branch (as it will cause conflicts with dev branch when we are sending notes using Quartz Syncer).
  • Make sure only way to make changes to quartz repo is by creating a dev to v4 PR and merging it.

Hosting

For hosting I am using Cloudflare Pages. Instructions can be found here on how to connect with GitHub repo to automate publishing.

In my quartz repo, I created a file wrangler.toml to define on where the build assets will be, and to disable both preview and workers dev URLs after each build process.

name = "quartz"
workers_dev = false
preview_urls = false
compatibility_date = "2026-02-21"
 
[build]
command = "npx quartz build"
 
[assets]
directory = "./public"

We can technically now keep adding Markdown file in the content folder and the CI / CD will build and publish the notes. But there is a better way discussed in the next section.

Important: Make sure to create a dev branch both local and remote. We will create a PR from dev branch against main / production branch to publish notes (it will save us Workers build minutes in Cloudflare).

Quartz Syncer

Why?

The challenge was since I was already using single Obsidian vault Second Brain to manage both private and public notes, and in order to publish public notes using Quartz, I could it do in 2 ways:

  1. I have not tested this method. Quartz expect all the Markdown files to be in content folder in order to generate static content. I could have moved the entire Obsidian vault in this folder and then later open the content folder as vault in Obsidian. Pretty neat, right? The only thing next I was meant to do, was to explicitly mark notes I wanted to publish using ExplicitPublish plugin (so that I have more control over not accidentally sharing private notes.)
  2. The other method was to install Quartz Syncer in Obsidian and use it to tag notes which I wanted to publish explicitly. I PREFERRED THIS METHOD. Because I was looking for some segregation between the concept of vault (which help me to manage both the public and private notes) and digital garden (only public notes). This method also gave me more peace of mind knowing I will be having staging area before I decide to publish anything publicly. I know this method introduces redundancy of notes but I don’t seem to care for now (maybe in the future?)

Instructions

  1. Install / enable the Quartz Syncer community plugin in Obsidian.
  2. Go to this plugin settings and add quartz repo URL (the one we cloned and own) in Remote URL.
  3. Add Username and Access Token.
  4. THIS IS IMPORTANT. For the branch, I added dev (a fresh branch I made earlier from v4 or main / production branch of quartz). We solve 2 problems with this approach:
    1. We can keep pushing new notes to dev branch and it will give us staging area where we have to create PR first in order to merge notes to main branch. This way we can review we are only merging notes which are meant to be shared by public.
    2. We save Workers build minutes in Cloudflare pages (free tier). Because every push to v4 was triggering build process in Cloudflare pages, costing more build minutes.
  5. Now Obsidian is ready to mark notes and push them to quartz repo.
  6. To publish any note, open command menu and run Quartz Syncer: Add publication flag and then Quartz Syncer: Open publication center.
  7. Review the new notes and changed notes and press publish button. (Make sure to not unselect Published notes because selecting them will unpublish them.)
  8. Go to dev branch and confirm the commits and once you feel like you have added enough notes to publish, just create a PR against main branch and merge it. The merge to main branch will trigger the build command in Cloudflare pages.

Theming

You can find community managed themes in this repo: https://github.com/saberzero1/quartz-themes

Graph View

Backlinks