Decision: Vercel Wiki Deployment

currentdecisiondecisionwikiverceldeployment

Deploy wiki markdown as a static Next.js site to Vercel for public read-only access.

Decision: Vercel Wiki Deployment

Context

The engineering wiki lives in wiki/ as markdown files with YAML-like frontmatter and double-bracket wiki-link syntax. The existing FastAPI server (server/wiki.py) renders these pages dynamically but is not publicly accessible. A lightweight public endpoint was needed for easy review.

Decision

  • Deploy a static Next.js site from site/ to Vercel.
  • At build time, read wiki/*.md, parse frontmatter via gray-matter, resolve double-bracket wiki links and `@file:` references, and render HTML via unified (remark + rehype).
  • Use output: 'export' for a fully static HTML export with zero serverless runtime cost.
  • Configure deployment via vercel.json at repo root.
  • Internal wiki links resolve within the Vercel site (/wiki/{slug}).
  • @file: references link to the GitHub repository on main.

Design Rationale

The fundamental goal was to make the engineering wiki readable by anyone with a browser, without requiring access to the running FastAPI server or the repository itself. Several approaches were evaluated:

  • Expose the FastAPI wiki API publicly: rejected because the FastAPI server (server/wiki.py) is a development and operational tool, not a public-facing service. Exposing it would require authentication decisions, rate limiting, TLS configuration, and ongoing uptime management for what is fundamentally a read-only documentation site.
  • GitHub Pages with Jekyll: a natural fit for repo-backed markdown, but Jekyll's frontmatter expectations and Liquid templating would require adapting the wiki's custom double-bracket wiki-link and `@file:` syntax. The Next.js approach in site/lib/wiki.ts gives full control over link resolution and rendering.
  • Render markdown client-side: would shift complexity to the browser, increase load times, and expose raw markdown files. Static pre-rendering produces fast, crawlable HTML with no client-side processing cost.

The output: 'export' configuration in Next.js was chosen specifically to avoid serverless function costs and cold-start latency. The entire site compiles to flat HTML files, making it effectively free to host on Vercel's edge CDN.

Assumptions & Constraints

  • Wiki content is public. This deployment assumes nothing in wiki/ is sensitive. All wiki pages are engineering documentation about the project's architecture and operations — no credentials, user data, or proprietary algorithms.
  • Build-time rendering is acceptable. Pages are rendered at build time, not on demand. This means wiki updates are only visible after a push to main triggers a Vercel rebuild. The latency (typically under two minutes) is acceptable for documentation that changes at code-review cadence.
  • Two rendering pipelines coexist. The FastAPI server uses Python markdown with TocExtension; the Vercel site uses unified (remark + rehype) in TypeScript. Both must resolve double-bracket wiki links and `@file:` syntax identically. This is a maintenance risk — changes to link resolution logic must be mirrored in both server/wiki.py and site/lib/wiki.ts.
  • @file: references point to main. The Vercel site resolves <a href="https://github.com/icosahedron10/lorewright/blob/main/path" class="source-ref"><code>path</code></a> references to https://github.com/icosahedron10/lorewright/blob/main/path. This assumes main is the canonical branch and that referenced files exist there. Links to deleted or renamed files will 404 on GitHub.
  • vercel.json is minimal. The configuration in vercel.json specifies only installCommand, buildCommand, and outputDirectory. Routing, headers, and redirects are left to defaults, which works because the static export produces self-contained HTML files.

Conceptual Model

The Vercel deployment creates a read-only projection of the wiki — a static snapshot built from the same markdown sources that the FastAPI API serves dynamically. The two systems form a diamond pattern:

wiki/*.md (source of truth)
   ├── server/wiki.py   → dynamic API for programmatic consumers
   └── site/lib/wiki.ts → static HTML for human readers

Both paths parse the same frontmatter, resolve the same link syntax, and render the same markdown. They differ only in when rendering happens (request-time vs. build-time) and who the audience is (API clients vs. browser users).

The double-bracket wiki-link resolution in site/lib/wiki.ts uses a slug-to-title map built from all pages at build time. Links to known slugs get a wiki-link CSS class; links to unknown slugs get broken-link. This mirrors the health-check concept from the FastAPI side — broken links are visible in the rendered output rather than silently swallowed.

The `@file:` reference resolution bridges the gap between documentation and code. By linking to specific files (and optionally line ranges) on GitHub, wiki pages maintain traceable provenance without embedding code snippets that would go stale.

Consequences

  • Wiki content is publicly readable at the Vercel deployment URL.
  • Every push to main triggers an automatic rebuild via Vercel's GitHub integration.
  • No Python runtime is required on Vercel — the site is pure static HTML/CSS/JS.
  • The FastAPI wiki API (/api/wiki/*) continues to serve the same content for programmatic consumers.
  • Dual rendering pipelines (Python and TypeScript) must be kept in sync when link resolution or sanitization logic changes — this is the primary ongoing maintenance cost of the decision.