Build a Static Website with Quartz

A Free Alternative to Obsidian Publish: How to Set Up Quartz for Publishing Your Notes

If you've been using Obsidian Publish to share your notes online but want a free, self-hosted alternative with more customization options, Quartz might be the perfect solution. In this guide, I'll walk you through setting up Quartz from scratch, syncing it with GitHub, and hosting your notes online—all for free.

Why Quartz Instead of Obsidian Publish?

Obsidian Publish is convenient, but it has some drawbacks:

• It's paid ($8/month)
• No self-hosting option—you're locked into Obsidian's service
• Limited customization—you can't tweak it as much as you might want
• Performance issues—it's been slow for me lately

Quartz, on the other hand, is free, open-source, and highly customizable. It's a static site generator designed to work seamlessly with Obsidian (though you don't have to use Obsidian).

How Quartz Works

When publishing Markdown notes online, there are three key components:

1. Editing & Storing Notes – Obsidian (or any text editor) handles this
2. Converting Markdown to HTML – This is where Quartz comes in
3. Hosting the HTML Online – We'll use GitHub Pages (free & reliable)

Quartz only handles the second step, meaning you'll still need:

• A way to write notes (Obsidian, VS Code, etc.)
• A hosting provider (GitHub Pages, Netlify, Cloudflare, etc.)

Step 1: Install Quartz

1. Clone the Quartz repository:

   git clone https://github.com/jackyzha0/quartz.git
   mv quartz your-vault-name
   cd your-vault-name

2. Install dependencies:

   npm install

3. Initialize Quartz:

   npx quartz create

   • Choose "Empty Quartz" for a fresh setup
   • Select "Shortest path" for Obsidian compatibility

Step 2: Set Up a GitHub Repository

1. Create a new GitHub repo (don't initialize it)
2. Link your local Quartz repo to GitHub:

   git remote add origin https://github.com/your-username/your-repo.git
   git push -u origin main

3. Sync changes:

   npx quartz sync

Step 3: Turn It Into an Obsidian Vault

1. Open the folder in Obsidian (File → Open → Select your repo)
2. Customize Obsidian (themes, plugins, hotkeys)
3. Add notes—Quartz expects a specific format:

   ---
   title: "Your Note"
   draft: false
   ---
   # Your content here...

   (You can use Templater for easy note creation.)

Step 4: Sync to GitHub Automatically

1. Push changes manually:

   npx quartz sync

2. Preview locally:

   npx quartz build --serve

   (This lets you check how your site looks before publishing.)

Step 5: Host on GitHub Pages

1. Create a GitHub Actions workflow:
   • In your repo, create .github/workflows/deploy.yml
   • Paste this config
2. Enable GitHub Pages:
   • Go to Settings → Pages
   • Set Source to GitHub Actions
3. Your site will deploy to username.github.io/repo-name

(Optional) Step 6: Use a Custom Domain

1. Buy a domain (e.g., yourdomain.com)
2. Set DNS records:
   • Add A records pointing to GitHub's IPs:

     185.199.108.153
     185.199.109.153
     185.199.110.153
     185.199.111.153

3. In GitHub Pages settings, add your domain and wait for DNS propagation

Final Thoughts: Should You Switch?

Quartz is powerful, but it's not for everyone. If you:

• Want simplicity → Stick with Obsidian Publish
• Love customization → Quartz is a great free alternative
• Need automation → Quartz + GitHub is a solid combo

I'll still use Obsidian Publish for most notes, but Quartz is perfect for personal projects. Try it out—and if you like it, consider supporting Jacky Zhao, the creator!

Enjoy publishing your notes for free! 🚀

(Thanks to Hey It's Gilbert from my Patreon Discord for inspiring this setup!)