I have been using Quartz 5 for about two days.
So by my habit, I changed a few things, merged a small code changes into PR, and then the site stopped loading.
Well, it was loading.
Cloudflare said the deployment was successful. The homepage returned HTTP 200. Everything looked healthy from the outside.
But the entire page was only a tiny redirect document pointing back to itself.
/ was refreshing to ./
forever.
Very entertaining HTTP 200.
First Problem: the Permalink I Never Added
My Obsidian note did not have a permalink field.
But the published copy on GitHub did:
permalink: /content/index.md
Quartz Syncer was generating it because I had enabled Enable permalinks in its settings.
After correcting the Syncer vault root, it changed to:
permalink: /index.md
Still broken.
The fix was to disable Enable permalinks inside Quartz Syncer and publish the homepage again.
Now the generated permalink was gone.
But the homepage was still refreshing itself.
Great.
Second Problem: Index Was Not a Harmless Alias
The homepage also had this:
aliases:
- Index
That looked like it would not make an issue.
It was not. It did made the issue.
Quartz generated an alias redirect for Index, which landed on index.html—the same output file used by the real homepage.
So the redirect page replaced the homepage and redirected / back to /.
I removed the Index alias and published again.
The homepage returned immediately.
Then I Thought Another Feature Disappeared
Before the fix, the bottom of the page showed:
5 items under this folder.
It listed:
- code
- daily
- decisions
- fixes
- projects
After fixing the routes, that block disappeared.
For a moment I thought I had broken something else.
I had not.
The listing belonged to the accidental /content/ folder page. Quartz was treating the wrongly published homepage as content/index, so it rendered a folder listing there.
The real root homepage is a normal Quartz content page. It does not show an automatic folder listing by default. The official Quartz 5 homepage behaves the same way.
After republishing the other six affected notes without generated permalinks, /content/ correctly disappeared and everything returned to its proper route.
Things I Learned Very Quickly
A successful deployment does not mean the generated page is correct. Like this quartz-5-font-issues-cloudflare-pages.
HTTP 200 does not mean the visitor received a usable page.
Quartz Syncer can add publishing metadata that is not present in the original Obsidian note.
An innocent-looking Index alias can collide with the actual homepage.
And sometimes the feature you think disappeared was only visible because the routing was broken in a very specific way.
Two days into Quartz 5.
Learning fast. Mostly by temporarily breaking things.