oxFlow Wiki

ADR-0002 — Wiki viewer is Quartz v4

4 min read

Context

We want a single wiki-style viewer that surfaces everything in this monorepo — formal specs, ADRs, research, meeting notes, BMAD-synced stories — with the feel of a digital garden (Wikipedia, Andrej Karpathy’s notes, Google Brain research wikis). Specifically:

  • Backlinks and a graph view — so readers can see how decisions, research, and specs connect.
  • Full-text search — across the whole corpus.
  • Plain .md workflow — multiple AI agents from four team members will write concurrently. Every extra authoring step (MDX, custom components, proprietary syntax) creates drift.
  • Wikilinks [[slug]] — slug-based so files can move without link rot.
  • Vercel deploy — existing infra, no new platform.
  • Free — small team, no SaaS budget yet.

A custom vanilla-JS SPA already lived in both old repos at /app/ (marked.js + DOMPurify, 27 registered docs, BR-### auto-linking). It is fine for a small doc set but has no graph, no backlinks, no search, and will not scale to the combined knowledge base.

Evaluated options:

FrameworkBacklinks / GraphSearchVercelPlain MDMulti-agent
Quartz v4native (wikilinks, graph, backlinks, link previews)Pagefind built-inNative (official guide)Obsidian-flavored .mdExcellent
Astro Starlight + starlight-site-graphplugin-basedPagefindNative.md + .mdxGood
Docusaurus v3community pluginsAlgolia/localWorksYesGood
Fumadocs / Nextranone nativeOramaNativeMDX-firstGood
MintlifynoneManaged AIHosted-onlyProprietaryEditor-gated
Obsidian PublishnativenativeNoVault-onlyNot git-native

We will use Quartz v4 as the wiki viewer. It is the closest match to the Karpathy/digital-garden feel, purpose-built for bidirectional links and graph views with zero configuration, free, open-source, and has an official Vercel hosting guide.

Decision

  • Scaffold Quartz v4 at apps/wiki/ in this monorepo.
  • Configure quartz.config.ts to point contentDir at ../.. (repo root) so the wiki indexes docs/, decisions/, research/, meetings/, status/, prompts/, raw-dumps/ without having to flatten them into a single folder.
  • Use ignore patterns to exclude apps/, archive/, app/, flows-app/, presentation/, prototypes/, proposal/, templates/, meta/, node_modules/, .git/, and non-markdown files.
  • Enable the default layout components: Graph, Backlinks, TagList, Explorer, Search (Pagefind).
  • Deploy to a separate Vercel project in Phase 2 on a new subdomain (tentative: wiki.design.3sixtyone.co).

The existing custom SPA at app/ is marked for retirement once Quartz is live — but stays functional through Phase 1 so nothing breaks.

Alternatives considered

  • Astro Starlight + starlight-site-graph plugin — strong runner-up. More flexible theme, official Vercel support. Rejected because graph/backlinks rely on a third-party plugin, the configuration surface is larger, and it nudges toward .mdx which hurts multi-agent plain-MD workflow.
  • Evolve the existing vanilla-JS SPA (app/) — zero migration. Rejected because we would have to build graph, backlinks, and search ourselves. More code to maintain as the knowledge base grows; agents must learn the custom app/app.js document registry.
  • Docusaurus — mature, but no native graph/backlinks, heavier build, less digital-garden feel.

Consequences

Positive

  • Graph view gives the user the birds-eye “what’s been done so far” surface they asked for.
  • [[wikilinks]] by slug mean files can move without breaking inbound links.
  • Pagefind search works offline, no Algolia account needed.
  • Plain .md stays git-native — every agent can write without a build step.

Negative

  • Quartz is Obsidian-flavored; we’ll need to nudge markdown style slightly (e.g. ![[image]] for embeds).
  • The theme is opinionated. Customising it to match BRANDING.md tokens is Phase 2 polish.
  • Custom SPA at app/ becomes redundant. Ship Phase 1 without retiring it (nothing breaks); retire in Phase 2 once Quartz is stable.

Follow-up

  • Phase 2: deploy apps/wiki/ to Vercel on a new subdomain.
  • Phase 2: customise Quartz theme to use BRANDING.md tokens (fonts, colour palette).
  • Phase 2: add a docs/progress.md birds-eye page that queries status: in-progress across the corpus.
  • Phase 2: retire app/ (legacy SPA).

Outcome (2026-04-21)

Shipped. Wiki is live at oxflow-wiki.design.3sixtyone.co. The subdomain shifted from the tentative wiki.design.3sixtyone.co above to the final oxflow-wiki.design.3sixtyone.co during deploy. The Vercel project is oxflow-wiki on the 361 admin team, linked to github.com/361-coders-nz/oxflow-hub (Root Directory apps/wiki, cleanUrls: true).

References

Graph View

Backlinks