Calab.ai Handbook

Graph View

01 Site Rendering Technology

7 min read

Edit this page

Context

We need to publish our internal Handbook (maintained in Obsidian) to the web with high fidelity to the local Obsidian vault experience. This includes supporting:

  • Obsidian content features (callouts, wikilinks, Mermaid diagrams, graph view, search, backlinks)
  • Dark mode and professional theming
  • Plugin-rendered content (e.g. Excalidraw via SVG export, Mermaid)
  • GitHub repository-based publishing workflow
  • Enforcement of contribution governance via CODEOWNERS, GitHub rulesets, and Entra ID team integration
  • Extensibility for future needs (e.g. AI assistant, administrative UI widgets)
  • Single-repository architecture (vault and build system colocated)

A decision is needed to select the publishing/rendering technology that will serve as the canonical web frontend of our company wiki.

Decision

We will use Quartz 4 as the static site generator for the Obsidian Handbook.

Amendment History

2026-02-13 — Technology Switch: Digital Garden → Quartz 4

Original decision (2026-02-11): Obsidian Digital Garden plugin + Eleventy static site template.

Amended decision (2026-02-13): Quartz 4 static site generator.

Reason for amendment: During implementation planning for Plan 02 (Deployment & Hosting), detailed technical analysis of the Digital Garden plugin source code (RepositoryConnection.ts, settings.ts) revealed three critical issues:

  1. Two-repository requirement is hardcoded. The Digital Garden plugin pushes notes via the GitHub API to a separate template repository. The plugin settings only accept githubToken, githubRepo, and githubUserName — there is no branch configuration. The plugin always targets the default branch of the configured repository. This cannot be changed without forking the plugin.

  2. PR-based governance is bypassed entirely. The plugin publishes by directly committing to the template repository’s default branch via the GitHub API, bypassing pull requests, branch protection rules, CODEOWNERS, and any review workflows. This directly contradicts Decision 01’s own requirement for “enforcement of contribution governance via CODEOWNERS, GitHub rulesets, and Entra ID team integration.”

  3. PAT token management overhead. The plugin requires a GitHub Personal Access Token with repository write permissions. This token must be manually created, stored in Obsidian’s plugin settings, renewed on expiry, and distributed to each contributor — introducing operational overhead and a security surface.

Quartz 4 resolves all three issues:

  • Single-repository architecture: Quartz installs into the same repo as the vault content
  • Git-native publishing: publishing = git push (or PR merge), fully compatible with branch protection, CODEOWNERS, and PR review workflows
  • No PAT required: GitHub Actions uses the built-in GITHUB_TOKEN for deployment

Consequences

  • Our internal GitHub repository remains the single source of truth for both vault content and the published site build system

  • The main branch serves as the deployable source, governed by PR approvals and GitHub Rulesets

  • Publishing is done via git push or PR merge — fully aligned with existing governance workflows (CODEOWNERS, branch protection, Entra ID team integration)

  • No Obsidian plugin is required for publishing — contributors commit and push via git (CLI, GitHub Desktop, or VS Code)

  • Content fidelity is preserved: Obsidian callouts, wikilinks, Mermaid diagrams, tags, syntax highlighting, and transclusions render correctly via the ObsidianFlavoredMarkdown transformer plugin

  • Theme is configurable but not pixel-identical to Obsidian — Quartz has its own theming system with customisable colors, fonts, and dark/light mode support

  • Excalidraw diagrams require SVG auto-export (via the Excalidraw Obsidian plugin) rather than native client-side rendering

  • Selective publishing is supported via publish: true frontmatter and the ExplicitPublish filter plugin, with ignorePatterns for excluding entire directories (e.g. _authoring/ and 99 Archive/)

  • Site features include: full-text search, graph view (local + global), backlinks, table of contents, popover previews, breadcrumbs, explorer (file tree), SPA routing, RSS feed, dark mode, syntax highlighting, and LaTeX support

Considered Alternatives

Quartz 4

Pros:

  • Git-native, single-repository architecture — vault and build system coexist in one repo

  • Built for Obsidian vaults: ships with ObsidianFlavoredMarkdown plugin supporting wikilinks, callouts, Mermaid, tags, highlights, transclusions, and block references

  • Publishing = git push — fully compatible with PR reviews, CODEOWNERS, branch protection, and Entra ID team integration

  • No Obsidian plugin dependency — no PAT token management, no token expiry risk

  • Batteries-included: full-text search, graph view, backlinks, table of contents, popover previews, breadcrumbs, explorer, SPA routing, RSS feed, dark mode, syntax highlighting, LaTeX, custom OG images

  • First-class GitHub Pages support with official GitHub Actions workflow

  • Active community: 11.2k+ stars, 3.5k+ forks, 246 contributors

  • Extensible via JSX components and custom plugins (TypeScript)

  • ignorePatterns (glob-based) for directory-level exclusions

  • ExplicitPublish filter for frontmatter-gated selective publishing

  • Hot-reload local preview via npx quartz build --serve

Cons:

  • Theme is not pixel-identical to Obsidian — uses its own configurable colour/font system (functionally equivalent, not visually identical)

  • No native Excalidraw rendering — requires SVG auto-export from the Excalidraw Obsidian plugin

  • No Dataview query support — dynamic queries must use alternative approaches (static tables, Mermaid charts, or custom Quartz components)

  • Publishing requires git knowledge — higher barrier for non-technical contributors (mitigated by guides and GitHub Desktop)

  • Requires Node.js v22+ for local builds

Rationale:

  • Chosen for its single-repository architecture, native git-based publishing workflow, and full alignment with our governance model (CODEOWNERS, PR reviews, branch protection, Entra ID teams). Provides all critical Obsidian content features while eliminating the operational overhead of PAT token management and two-repository coordination.

Obsidian Digital Garden

Pros:

  • Best visual fidelity to Obsidian (pulls exact Obsidian theme CSS)

  • Plugin-aware: supports Excalidraw (native client-side rendering), Dataview (static render at publish time), Mermaid, Canvas

  • Low-friction “click to publish” workflow inside Obsidian

  • Selective publishing via dg-publish: true frontmatter

  • GitHub-friendly, deployable to GitHub Pages, Azure SWA, Netlify, Vercel

  • Extensible via custom HTML/JS slots and Nunjucks templates

Cons:

  • Requires a separate template repository — hardcoded in the plugin; no single-repo option

  • Bypasses PR-based governance entirely — publishes directly to the template repo’s default branch via GitHub API, skipping pull requests, CODEOWNERS, branch protection, and review workflows

  • Requires a GitHub Personal Access Token per contributor — token management, expiry, and renewal overhead

  • Template is Eleventy-based (Nunjucks templates) — less modern than JSX/TypeScript extensibility

  • pathPrefix issues on GitHub Pages project sites (requires custom domain or template modification)

  • Contributors can publish without any review — governance is bypassed by design

Why not chosen:

  • The two-repository requirement and governance bypass are fundamental architectural constraints that cannot be worked around without forking the plugin. These directly conflict with our requirements for PR-based content review, CODEOWNERS enforcement, and single-repository simplicity.

MkDocs (Material theme)

Pros:

  • Mature, professional-looking docs theme

  • Excellent for traditional documentation

  • GitHub Pages/Azure SWA native

Cons:

  • Does not natively support Obsidian plugins (Excalidraw, Canvas, etc.)

  • Requires conversion scripts for wikilinks, embeds, callouts

  • Less visual and functional parity with Obsidian

Why not chosen:

  • Too many workarounds needed for Obsidian content fidelity. Better for classical documentation, not for mirroring the vault experience.

Docusaurus / Obsidiosaurus

Pros:

  • Full React extensibility (ideal for embedding custom components)

  • Excellent for dynamic/custom sites

Cons:

  • Requires Markdown-to-MDX conversion

  • No native Obsidian support (theme, plugins, etc.)

  • Heavier developer overhead

Why not chosen:

  • Excellent for app-like sites, but overkill and too detached from Obsidian authoring. Adds complexity without improving the contributor experience.

Next Actions

  • Install Quartz 4 scaffolding into the calab-handbook repository

  • Configure quartz.config.ts with vault-specific settings (content directory, ignorePatterns, ExplicitPublish, theme)

  • Create GitHub Actions workflow for building Quartz and deploying to GitHub Pages

  • Configure GitHub Pages source to “GitHub Actions”

  • Add publish: true frontmatter to content and validate end-to-end publishing pipeline

  • Apply CODEOWNERS, rulesets, and Entra-based approver enforcement (deferred — see docs/CODEOWNERS_DEFERRED.md)

  • Define publishing workflow and contributor guide

  • Remove Digital Garden plugin from Obsidian (community-plugins.json)

Backlinks

Graph View

Graph View