| 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
yarn dev
yarn build
yarn preview
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
