Calab.ai Handbook

Graph View

02 Site Hosting Platform

2 min read

Edit this page

Context

We are deploying our Obsidian-based Handbook to the web using Quartz 4, which generates a static site from the Obsidian vault. The intended audience for the handbook is strictly internal — there is no requirement to expose the content externally or support dynamic server-side APIs as part of the documentation platform.

We need to determine the most appropriate and lightweight hosting platform for a static site that supports our internal-only access model and integrates well with our Git-based governance processes.

Decision

We will host the site using GitHub Pages.

Consequences

  • Site will be deployed automatically via GitHub Actions from the main branch of the handbook repository
  • The hosting stack remains fully Git-native, lightweight, and free
  • All governance (CODEOWNERS, PR reviews, branch protection, Entra-synced GitHub Teams) remains intact and enforceable via the repository workflow
  • Authentication or access control is not required, as the site will not be published to external users or endpoints
  • If internal-only access becomes required in future, we can transition the build output to an Azure-hosted private web app (to be covered in a separate decision)

Considered Alternatives

GitHub Pages

Pros:

  • GitHub-native and trivial to integrate with our publishing workflows
  • Free for public or private repos
  • Supports custom domains and HTTPS out of the box
  • Familiar CI/CD process for our engineering team

Cons:

  • No built-in authentication or access control
  • No preview/staging environments

Rationale:

  • Since the site does not require external access or auth integration, GitHub Pages offers the cleanest, lowest-friction hosting model. All governance and publishing controls are handled by GitHub repo permissions and workflows.

Azure Static Web Apps

Pros:

  • Native support for Azure AD authentication (for gated access)
  • Support for staging environments and preview URLs
  • Integrated Azure Functions support for dynamic content

Cons:

  • Higher setup and operational complexity
  • Unnecessary for a purely static, unauthenticated site

Why not chosen:

  • Adds complexity we don’t currently need. Any dynamic functionality (e.g. chatbots, admin tools) will be handled in a future decision and deployed as separate services.

Next Actions

  • Configure GitHub Pages for the handbook repository
  • Set up GitHub Actions workflow for building Quartz and deploying to GitHub Pages via artifacts
  • Ensure main branch remains protected with CODEOWNERS and rulesets for governance
  • If future need arises for access restriction or dynamic hosting, raise a follow-up decision

Backlinks

Graph View

Graph View