Quartz -> Starlight

Quartz to Starlight

After reviewing the plan outlined in [Quartz MDX](Quartz MDX.md), it seems that it is better to implement the look and feel of Quartz 4 in Starlight in order to enable support for MDX files.

Should we re-implement Quartz in Starlight?

Short answer: yes, if you need MDX + hydration, you’ll get ~100% feature parity and more control, with a clean migration path.

Starlight

Quartz Feature List

Positioning: Why Starlight over Quartz for your end-state

You want interactive MDX and client-side islands; Astro/Starlight is built for that (MDX + hydrated components), while Quartz focuses on static SSR. Starlight also ships accessible navigation, theme hooks, and a plugin ecosystem (DocSearch, link validators, versions, etc.), so you’re composing features instead of forking a generator.

Starlight

Plugins & Integrations

Quartz Architecture

Look and feel parity

Start from the Obsidian-style Starlight theme to match Quartz’s visual language (dark/light, three-pane feel), then tweak layout and tokens. This gets you close to Quartz’s “Publish” aesthetic without re-implementing its renderer.

Starlight Obsidian Theme

Starlight Themes

Quartz Feature List

Feature-by-feature mapping (Quartz to Starlight)

Search (Quartz “Full-text Search”) to Starlight Pagefind (default) or official DocSearch plugin when you need scale.

Starlight Config: pagefind

Plugins & Integrations

Graph View to starlight-site-graph; same mental model, configurable styling.

starlight-site-graph Docs

Backlinks to compute from the link graph and render in a page component (examples in the wild).

Using Obsidian with Starlight

Backlinks recipe

Wikilinks/Embeds/Callouts to starlight-obsidian for ingestion; native Asides for callouts.

starlight-obsidian

Asides

Popover Previews to add a hover preview component per recipe.

Link previews recipe

Mermaid/Math to astro-mermaid (client) or SSR alternatives; add remark-math + KaTeX if needed.

astro-mermaid

Astro RSS/Math patterns

RSS Feed to @astrojs/rss.

Astro RSS

Comments to drop in Giscus plugin from ecosystem.

Plugins & Integrations

Reader Mode / Compact view to view-modes/fullview community plugins or small CSS toggles.

Plugins & Integrations

Starlight Themes

SPA Routing to Starlight favors multi-page + islands; approximate Quartz’s SPA feel with prefetch + view transitions.

Plugins & Integrations

Quartz Feature List

Obsidian vault parity

Use starlight-obsidian to import your vault into src/content/docs, preserving wikilinks, embeds, callouts, tags/aliases, and assets; it can also inject a generated sidebar group. It’s the fastest path off Quartz with semantics intact.

starlight-obsidian

Quartz visual parity without Quartz

The theme + component system in Starlight lets you reconstruct Quartz’s three-column layout (left nav, content, TOC/graph/backlinks on the right) while keeping MDX/interactivity. Start with the Obsidian theme, then add a right-rail slot for Graph/Backlinks.

Starlight Obsidian Theme

starlight-site-graph Docs

Starlight

// astro.config.mjs — Starlight with Obsidian, Graph, DocSearch, Mermaid
// refs: [Starlight](https://starlight.astro.build/) [Plugins](https://starlight.astro.build/resources/plugins/) [starlight-obsidian](https://starlight-obsidian.vercel.app/) [site-graph](https://github.com/Fevol/starlight-site-graph) [astro-mermaid](https://www.starlightstarter.com/documentation/options/mermaid/)
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
import starlightObsidian, { obsidianSidebarGroup } from 'starlight-obsidian'
import siteGraph from 'starlight-site-graph/plugin'
import docsearch from '@astrojs/starlight-docsearch'
import mermaid from 'astro-mermaid'
import mdx from '@astrojs/mdx'

export default defineConfig({
  integrations: [
    mermaid({ autoTheme: true }),
    mdx(),
    starlight({
      title: 'Notes',
      plugins: [
        starlightObsidian({ vault: '../vault', output: 'notes' }),
        siteGraph({ route: '/graph', sidebarLink: true }),
        docsearch({ appId: 'XXX', apiKey: 'XXX', indexName: 'XXX' }),
      ],
      sidebar: [
        { label: 'Guides', items: ['intro'] },
        obsidianSidebarGroup,
      ],
      pagefind: true,
    }),
  ],
})

Backlinks component sketch

Compute the link graph once (same data starlight-site-graph uses) and render “Linked mentions” per page. This mirrors Quartz’s Backlinks UX and can live in a right-rail slot under the TOC.

Using Obsidian with Starlight

Backlinks recipe

Quartz Feature List

Hover previews

Use the link-preview recipe to show a popover of internal links on hover; gate it behind a media query or “Reader mode” toggle to keep motion/accessibility tight.

Link previews recipe

Quartz Feature List

Search strategy

Start with Pagefind (zero external service). If you need analytics/multi-index, flip to DocSearch via the official plugin—no content changes required.

Starlight Config: pagefind

Plugins & Integrations

Mermaid and math

Prefer astro-mermaid for client rendering with theme sync; add remark-math + KaTeX for equations if your vault includes LaTeX. Both are well-trodden in Astro.

astro-mermaid

Starlight

RSS and “Recent Notes”

Use @astrojs/rss to publish feeds; “Recent Notes” is a trivial content-collection query sorted by modified time.

Astro RSS

Starlight

Where Starlight differs from Quartz

SPA Routing: Quartz offers SPA navigation; in Starlight, combine islands + prefetch + view transitions for similar perceived speed (keeps SEO and resilience).
Reader Mode: ship as a CSS/DOM toggle or adopt community view-mode plugins.
Private Pages: handle at the platform edge (e.g., host auth or Astro middleware) rather than a static filter.

Quartz Feature List

Plugins & Integrations

Starlight

Recommended plan

Stand up Starlight with starlight-obsidian and the Obsidian theme for instant parity.
Add starlight-site-graph, backlinks component, and hover previews.
Start with Pagefind; switch to DocSearch later if needed.
Layer Mermaid/KaTeX, comments, RSS.
Tune CSS tokens to nail Quartz aesthetics and ship.

starlight-obsidian

starlight-site-graph Docs

Starlight Themes

Starlight Config

Bottom line

Re-implementing Quartz in Starlight is not only feasible—it yields MDX + hydration, richer plugins, and long-term maintainability. You’ll match Quartz’s UX (search, graph, backlinks, previews) and keep Obsidian semantics, while gaining interactive components and a modern theming surface.

Quartz Feature List

Starlight

starlight-obsidian

starlight-site-graph Docs