Skip to content

Vault Web Setup

Decision

Use Quartz v5 rather than MkDocs/Material for the Hermes vault static web view.

Quartz is the better fit because the source vault is Obsidian-native:

  • Preserves Obsidian-style wikilinks and backlink/navigation concepts.
  • Reads Markdown with YAML frontmatter without needing a docs-specific rewrite.
  • Produces a mobile-friendly static site that can be served read-only.
  • Keeps the canonical writable vault separate from any rendered/public copy.

MkDocs/Material remains a good documentation-site renderer, but it would require more normalization of Obsidian conventions and would make the vault feel less like a graph/wiki.

Repositories and directories

  • Canonical local vault: /home/adam/hermes-vault
  • GitHub backup remote: https://github.com/ParrottPy/hermes-vault.git
  • Local Quartz checkout: /home/adam/quartz
  • Test build output: /tmp/hermes-vault-quartz-public

The vault remote is for backup/sync. Do not grant write access to work machines or sync a writable working copy there. Any web deployment should consume a read-only clone or build artifact.

Build command

Quartz v5 requires Node.js 22+. The system Node on this host may still be older, so the verified non-invasive build path is to run Quartz with an ephemeral Node 22 binary from npx:

# Regenerate the Quartz community-plugin index if .quartz/plugins/index.ts is missing
cd /home/adam/quartz
npx -y -p node@22 -p tsx node --import tsx -e 'import("./quartz/plugins/loader/gitLoader.ts").then(m=>m.regeneratePluginIndex({verbose:true}))'

# Build the Hermes vault into a static output directory
npx -y -p node@22 node /home/adam/quartz/quartz/bootstrap-cli.mjs \
  build \
  -d /home/adam/hermes-vault \
  -o /tmp/hermes-vault-quartz-public \
  --concurrency=1

Verified result on 2026-07-03:

  • Quartz v5.0.0
  • 154 Markdown input files found from /home/adam/hermes-vault
  • 685 static files emitted to /tmp/hermes-vault-quartz-public
  • Build completed successfully; only LaTeX compatibility warnings were reported for existing note content.

Configuration notes

/home/adam/hermes-vault/quartz.config.yaml records the vault-specific intent: Hermes Vault title, Obsidian-friendly ignore patterns, and wikilink/frontmatter/backlink support.

Current build verification used the Quartz checkout from /home/adam/quartz and the vault as the content directory. Before turning this into a hosted deployment, standardise one of these paths:

  1. Keep Quartz as a separate renderer repo and pass -d /home/adam/hermes-vault during builds; or
  2. Move/copy the active Quartz config into /home/adam/quartz/quartz.config.yaml and keep the vault repo as content only.

Do not create a writable rendered copy of the vault on work machines.

Phone access target

Target outcome: Adam can open a read-only, mobile-friendly Hermes vault from his phone without exposing the canonical writable vault.

Recommended path:

  1. Cloudflare Pages for hosting — deploy the Quartz static output to a Pages project such as hermes-vault.
  2. Cloudflare Access in front of it — allow only Adam's Google account / approved emails. Do not make the vault public unless a publish allowlist is added first.
  3. GitHub Actions or Prefect deployment automation — rebuild and redeploy on every master push, plus a scheduled daily drift check.
  4. Read-only content flow — Hermes commits/pushes curated vault updates; the phone site only consumes rendered static artifacts.
  5. Freshness monitoring — store the deployed git SHA in the build artifact and alert Slack if the site lags the vault remote by more than 24 hours.

Phone UX:

  • Use the Cloudflare Pages URL first, then add a custom domain later if useful.
  • Open the Access-protected URL on iPhone/Android, authenticate once with Google/OTP, then "Add to Home Screen" for app-like access.
  • Quartz gives responsive navigation/search; no Obsidian app sync is required for read-only consumption.

Deployment follow-up

Phase 1a proves the renderer decision and local build path. The next implementation slice is to make the build reproducible and hosted:

  • Standardise the Quartz build so it does not depend on a manually prepared /home/adam/quartz checkout.
  • Add a deploy pipeline from the private ParrottPy/hermes-vault repo to Cloudflare Pages.
  • Put Cloudflare Access in front of the Pages site before adding sensitive/private folders.
  • Add freshness monitoring for the daily news/research ingestion cycle.