Quartz Migration Changelog

Quartz v4 Migration — Changelog & Post-Mortem

Date: 2026-02-27 to 2026-02-28 Status: Reverted — returning to Astro/Starlight Decision: Quartz v4 had too many link resolution issues and the visual result wasn’t satisfactory. Reverting to the Astro/Starlight build that was already working.

What Was Attempted

Migrated the KB site from Astro + Starlight to Quartz v4.5.2, deployed via GitHub Actions CI to Cloudflare Pages.

Architecture

CI-only approach: Quartz cloned fresh at build time (not committed to vault repo)
Config files: quartz.config.ts, quartz.layout.ts, custom.scss committed to vault root, copied into Quartz at build
Static assets: _static/logo-light.png, _static/logo-dark.png copied to Quartz’s static dir
Link patch: scripts/patch-quartz-links.js patched Quartz’s path.ts at build time to fix wikilink resolution
Post-build: sed injection for logo <img> tag, light-mode default, noindex meta

Files Added for Quartz (now removed/reverted)

quartz.config.ts — Quartz configuration (Inter fonts, Baseworks brand colors, “shortest” link mode)
quartz.layout.ts — Layout with Explorer, Search, Darkmode, Graph, TOC, Backlinks
custom.scss — Custom styles (wider sidebar, tinted background, SVG folder/file icons, search pill, logo sizing)
scripts/patch-quartz-links.js — Monkey-patches Quartz’s transformLink() to fix wikilink resolution
scripts/dev-quartz.sh — Local dev helper script
_static/logo-light.png — Resized hexagon BASEWORKS logo (600x124)
_static/logo-dark.png — Dark mode logo variant
.github/workflows/deploy.yml — Rewritten for Quartz build pipeline

Design Work

Wider sidebar (380px vs default 320px)
Tinted sidebar background (#f0f0f2 light, #1c1c1e dark) via body background color
Border separator between sidebar and content
2rem column-gap between sidebar and content
Lucide SVG folder/file icons via CSS mask-image
Bordered pill-style search bar
Logo injection via post-build HTML sed replacement
Subtler metadata, breadcrumbs, footer

Issues Encountered

1. Wikilink Resolution — Fundamental Problem

Quartz v4’s “shortest” mode (CrawlLinks) only matches the last filename segment of a target. This fails for:

Partial paths: [educational-programs](/areas/educational-programs/educational-programs/) — the multi-segment target doesn’t match against single-segment filenames
Relative paths: [practice-sessions](/areas/educational-programs/practice-sessions/practice-sessions/) — the ../../ prefix stays in the matching string, preventing any match
Inline hashtags: #concordia in markdown body gets resolved by OFM to ../../tags/concordia, then CrawlLinks re-processes it and the fallback doubles the ../ traversal

Patches applied (3 iterations):

Added suffix matching after filename matching
Strip ../ and ./ from target before matching
Strip ../ and ./ from fallback path too

Even after all patches, links were still fragile. Quartz’s link model is fundamentally different from Obsidian’s and requires extensive patching for a vault with complex cross-directory links.

2. Cloudflare Pages Production Branch

CF Pages default production branch is main, but our repo uses master
Deployments went to preview URLs until we added --branch=main --commit-dirty=true

::before pseudo-element with left: -9999px caused horizontal scrollbar
Switched to body background color approach (body gets sidebar tint, center/right override to normal)

4. Broken Links Summary (at time of revert)

0 links with the ./ fallback pattern (fixed by patches)
~40 links to notes that don’t exist yet in the vault (not a Quartz issue — these are placeholder wikilinks to uncreated notes)
4 links to transcript files with shortened names that don’t match actual filenames

Backup Tags (preserved in git)

backup/pre-quartz-migration — Last commit before any Quartz changes
backup/quartz-local-verified — First successful local build
backup/quartz-workflow-ready — First CI deployment
backup/quartz-ui-redesign-verified — After logo/sidebar redesign
backup/pre-link-fix-and-icons — Before SVG icons and link patching

Revert to Astro/Starlight

Date: 2026-02-28

Restored deploy.yml from backup/pre-quartz-migration tag (Astro build pipeline)
Restored original index.md
Removed all Quartz-specific files: quartz.config.ts, quartz.layout.ts, custom.scss, scripts/patch-quartz-links.js, scripts/dev-quartz.sh
Initial Astro deployment went to a preview URL (not production) because deploy.yml was missing --branch=main — Cloudflare Pages production branch is main but our repo uses master
Fixed by adding --branch=main --commit-dirty=true to the wrangler deploy command
Astro/Starlight site confirmed live on kb.baseworks.com

Lessons Learned

Quartz’s link resolution is not Obsidian-compatible — It works for simple flat vaults but breaks badly with deep directory structures and relative-path wikilinks
Astro/Starlight gives more control — Custom link resolution can be implemented properly in the sync script
Test link resolution first — Before investing in visual design, verify the build tool handles the vault’s linking patterns
The design assets are reusable — Logo files, color palette, Inter font choice, sidebar layout concept can carry over to Astro

What to Carry Forward to Astro

Hexagon BASEWORKS logo (_static/logo-light.png)
Inter font family
Brand colors (dark: #182654, secondary: #3a5bd9, tertiary: #4a6cf7)
Tinted sidebar concept
SVG folder/file icons
Proper wikilink resolution in sync script
Tina CMS integration (Phase 2)