website-development

name	website-development
description	Website development patterns for the Beluga AI docs and marketing site. Use when building, styling, or adjusting Astro components, layouts, pages, and interactive elements — NOT for writing documentation content (see content-writer).

Website Development Patterns

Tech Stack

• Framework: Astro 5 with Starlight documentation theme
• Styling: Tailwind CSS 4 (via @tailwindcss/vite plugin)
• Components: Astro components (.astro) — use React 19 (.tsx) only when client-side interactivity is required
• Build: Vite 7, TypeScript 5
• Extras: astro-vtbot (view transitions), astro-embed, astro-font, Mermaid diagram rendering (custom rehype plugin), Sharp for image optimization, Satori + Resvg for OG image generation

Project Structure

.
├── astro.config.mjs              # Astro + Starlight + Tailwind + redirects config
├── src/
│   ├── components/               # Shared Astro components
│   │   ├── override-components/  # Starlight component overrides (10 wired in astro.config.mjs)
│   │   ├── marketing/            # Marketing-page primitives (MarketingHeader, MarketingFooter, Hero, CTA, etc.)
│   │   ├── search/               # Search override internals
│   │   └── user-components/      # Custom reusable components
│   ├── config/                   # Site config JSON (config, sidebar, social, theme, locals, menu.{en,fr})
│   ├── content/                  # Markdown/MDX content (managed by content-writer, NOT this persona)
│   │   ├── docs/                 # Starlight docs collection
│   │   ├── i18n/                 # UI translations
│   │   └── sections/             # ctaSection collection (marketing CTAs)
│   ├── content.config.ts         # Content collection schema
│   ├── data/                     # Static data imported at build time
│   ├── layouts/                  # Page layouts
│   ├── lib/                      # Utilities, rehype-mermaid, og-image, provider-catalog
│   ├── pages/                    # Marketing routes outside Starlight (includes /404)
│   ├── styles/                   # CSS split by concern
│   ├── assets/                   # Build-time assets
│   └── tailwind-plugin/          # Custom Tailwind plugins
├── public/
│   ├── godoc/                    # Generated by scripts/fetch-docs-bundle.sh (gitignored)
│   ├── og/                       # OG images generated by src/lib/og-image.ts
│   ├── CNAME                     # beluga-ai.org custom domain for GitHub Pages
│   └── <static assets>
├── scripts/
│   └── fetch-docs-bundle.sh      # Pulls godoc + project-reports from framework releases
├── tsconfig.json
└── package.json

Scope & Boundaries

This persona handles:

• Astro component development (.astro, .tsx)
• Starlight theme customization and component overrides
• Tailwind CSS styling and custom plugins
• Page layouts, navigation, sidebar, header, footer
• Interactive UI elements (tabs, accordions, search, theme switching)
• Responsive design and accessibility
• Build configuration (Astro, Vite, Tailwind)
• Performance optimization (image handling, view transitions, bundle size)
• Custom rehype/remark plugins for content rendering
• OG image generation pipeline

This persona does NOT handle:

• Writing or editing long-form content (blog posts, tutorials, guides, docs copy) — that is the content-writer agent's job
• Framework Go code or architecture — file an issue in lookatitude/beluga-ai (the framework repo)
• Runnable code examples — file an issue in lookatitude/beluga-examples (the examples repo, when it exists)

Conventions

Component Rules

• Astro components for static/server-rendered UI (default choice)
• React components only when client:* directives are needed (interactive widgets)
• Component files use PascalCase: HeroTabs.astro, LinkButton.astro
• Override components mirror Starlight's naming in override-components/ — only overrides listed in astro.config.mjs are active; files in the directory that aren't wired there are dead
• Marketing primitives go in components/marketing/
• User-facing reusable components go in user-components/

Styling Rules

• Use Tailwind utility classes as the primary styling approach
• Custom CSS goes in src/styles/ — split by concern
• Custom Tailwind plugins in src/tailwind-plugin/ for project-specific utilities
• Respect dark/light mode — always provide both variants
• Use CSS custom properties from theme config for brand colors

Path Aliases

• @/ and ~/ both resolve to src/ (configured in astro.config.mjs)
• Use these aliases in all imports: import X from "@/components/X.astro"

Starlight Overrides

• Override Starlight components by placing replacements in src/components/override-components/
• Register overrides in astro.config.mjs under starlight({ components: { ... } })
• Keep overrides minimal — extend rather than replace when possible
• Upstream Starlight updates may require refreshing these; touch carefully

Configuration

• Site config: src/config/config.json
• Sidebar: src/config/sidebar.json
• Social links: src/config/social.json
• Theme: src/config/theme.json
• Locales: src/config/locals.json
• Menus: src/config/menu.{locale}.json (en, fr)

Docs bundle from framework

• scripts/fetch-docs-bundle.sh pulls docs-bundle.tar.gz from the latest lookatitude/beluga-ai release
• Extracts godoc HTML into public/godoc/ (gitignored) and splices raw report bodies into src/content/docs/docs/contributing/project-reports/{changelog,security,code-quality}.md (tracked stubs with frontmatter)
• Never regenerate godocs locally; the bundle is the contract with the framework repo
• Never commit spliced report body changes — they regenerate on every build

Development Commands

yarn install    # install deps (yarn, not npm)
yarn dev        # Astro dev server
yarn build      # Production build → dist/
yarn preview    # Preview the built dist/

Node 22. See CLAUDE.md for the full deploy model and three triggers.

Don'ts

• Don't edit Markdown content files under src/content/docs/** or blog/tutorial pages — that's content-writer's job
• Don't introduce new CSS frameworks or UI libraries without explicit approval
• Don't break Starlight's content collection schema (src/content.config.ts)
• Don't hardcode text strings — use config files or Starlight's i18n system
• Don't add client-side JavaScript when Astro's server-rendering suffices
• Don't commit node_modules/, dist/, or public/godoc/ (the latter is regenerated each build)
• Don't commit spliced project-report body changes
• Don't regenerate godocs locally — pull the bundle from framework releases