ADR-007: Astro for Website and Documentation

Status: Accepted Date: 2026-01-15

Context

SiliconGhetto needs a marketing website and a documentation site. Both should produce static HTML for fast loading, easy deployment, and minimal hosting requirements. The sites should support Markdown content, have good developer experience, and integrate with the monorepo structure.

Options Considered

1. Astro (chosen)

  • Static-first with optional islands of interactivity
  • Native Markdown and MDX support
  • Content collections for structured documentation
  • Ships zero JavaScript by default
  • Component-based with .astro templates
  • Built-in support for multiple frameworks if needed later

2. Next.js (Static Export)

  • Powerful but heavier than needed for static content
  • React dependency adds bundle size even for static pages
  • SSR features are unnecessary for our use case
  • Overkill for documentation

3. Hugo

  • Extremely fast builds
  • Go templates have a steep learning curve
  • Limited component reuse
  • Theme ecosystem varies in quality

4. VitePress

  • Excellent for documentation
  • Vue-based — adds a framework dependency
  • Less flexible for marketing pages
  • Opinionated structure

Decision

Use Astro for both the marketing website (apps/website/) and the documentation site (apps/docs/). Both sites render to static HTML and are deployed as static files to the Hetzner server.

Consequences

Positive

  • Zero-JS pages by default — fast load times
  • Markdown content in docs-content/ is consumed by the docs site via content collections
  • .astro components are intuitive (HTML + frontmatter)
  • Same tooling for both sites reduces cognitive overhead
  • Static output deploys trivially (rsync to server)

Negative

  • Astro is newer than alternatives — smaller ecosystem
  • Team must learn Astro’s component model
  • No SSR capabilities if dynamic features are needed later
  • Node.js build dependency

Mitigations

  • Astro’s learning curve is gentle for anyone who knows HTML
  • If dynamic features are needed, Astro supports islands of React/Svelte/Vue
  • Pin Astro version and update deliberately
  • pnpm workspace integration keeps Node dependencies organized

Site Structure

apps/
├── website/          # Marketing site
│   ├── src/pages/    # index, about, demos, roadmap, licensing, compatibility
│   └── src/layouts/  # Base layout with navigation
│
└── docs/             # Documentation site
    ├── src/pages/    # Renders docs-content/ as pages
    └── src/layouts/  # Docs layout with sidebar navigation

docs-content/         # Markdown source (shared, consumed by docs site)
├── adr/
├── architecture/
├── guides/
├── reference/
└── roadmap/

References