---
applyTo: "**/*.astro"
applyTo: "astro.config.mjs"
applyTo: "astro.config.*.mjs"
applyTo: "src/sites/**"
applyTo: "src/shared/**"
---

# Astro Website Instructions

## Commands

```bash
npm run dev      # Dev server at localhost:4321
npm run build    # Build to dist/
npm run preview  # Preview production build
```

## Integrations

**Active integrations:**
- `@astrojs/sitemap` - Auto-generates sitemap from pages
- `@astrojs/partytown` - Offloads heavy scripts to web workers (for analytics)
- `@astrojs/mdx` - MDX support for content with components
- Built-in prefetch - Viewport-based link prefetching (prefetchAll: true)

**Partytown usage:**
Use for third-party analytics scripts to offload them to web workers:
```astro
<script type="text/partytown" src="https://www.googletagmanager.com/gtag/js?id=..."></script>
```

## Layout System

**Two layouts available:**

### BaseLayout (Regular Pages)
Use for pages without hero sections (contact, privacy, etc.):
```astro
---
import BaseLayout from '@shared/layouts/BaseLayout.astro';
---
<BaseLayout
    title="Page Title | CULTSCALE"
    description="Page description"
>
    <!-- content -->
</BaseLayout>
```

**Features:**
- Relative header with proper spacing
- Bottom padding on mobile (4rem) for breathing room
- Centered logo on mobile

### HeroLayout (Hero Pages)
Use for pages with hero sections (index, about):
```astro
---
import HeroLayout from '@shared/layouts/HeroLayout.astro';
---
<HeroLayout
    title="Page Title | CULTSCALE"
    description="Page description"
    ogTitle="Optional OG title override"
    ogDescription="Optional OG description override"
>
    <section class="hero">
        <!-- hero content -->
    </section>
    <!-- rest of content -->
</HeroLayout>
```

**Features:**
- Absolute positioned header (overlay on hero)
- Hero-specific JavaScript (smooth scroll, parallax, graph animations)
- Inherits from BaseLayout via composition
- Centered logo with proper mobile spacing

**Layout Props:**
- `title` (required) - Page title
- `description` (required) - Meta description
- `keywords` (optional) - Meta keywords, defaults to standard set
- `ogTitle` (optional) - Override OG title, defaults to title
- `ogDescription` (optional) - Override OG description, defaults to description
- Do **not** pass deprecated props like `ogUrl`, `canonicalPath`, or `currentPage`—BaseLayout derives canonical/OG URLs from `Astro.url` automatically.

**URLs are derived automatically:**
- Canonical URL: Generated from `Astro.url.pathname` and `Astro.url.origin`
- OG URLs: Same as canonical
- Never hardcode site URLs - use `Astro.url`

## Asset Imports

```astro
---
import heroImg from '@assets/src/cultscale-audience-connection.jpg';
import logo from '@assets/src/cultscale-logo.svg';
import favicon from '@assets/out/cultscale-favicon.ico';
---
<img src={heroImg.src} alt="Hero" />
<link rel="icon" href={favicon.src} />
```

## Scripts

**External scripts for page-specific functionality:**
- `src/shared/scripts/hero.ts` - Hero page interactions (loaded by HeroLayout)
  - Lenis smooth scrolling
  - Parallax effects
  - Reveal animations
  - Graph scroll animations

**Import pattern:**
```astro
<script src="@shared/scripts/hero.ts"></script>
```

## Public Directory

Each site’s `public/` directory (e.g. `src/sites/cultscale/public/`) only contains:
- `robots.txt`
- `_redirects` (Cloudflare shortlinks)
- `_headers` (Cloudflare security/cache headers)

All images, icons, and assets are imported from `src/assets/` and served by Astro's build system.

## Sitemap

Sitemap is automatically generated by `@astrojs/sitemap` integration during build. It discovers all pages under `src/sites/**/pages/` and creates `sitemap-index.xml` and `sitemap-0.xml` in the build output (`dist/`). No manual maintenance needed.

## URL Rules

- Root-relative paths: `/about`, `/call`
- Use shortlinks from `_redirects`: `/linkedin`, `/calendar`, etc.
- All absolute URLs derived from `Astro.url.origin`

## Prefetching

All links are prefetched as they enter the viewport (viewport strategy). This happens automatically via `prefetch.prefetchAll: true` in config.

To disable prefetch on specific links:
```html
<a href="/heavy-page" data-astro-prefetch="false">Heavy Page</a>
```

To use immediate prefetch:
```html
<a href="/critical-page" data-astro-prefetch="load">Critical Page</a>
```

## MDX Support

You can now create `.mdx` files under `src/sites/**/pages/` to use markdown with embedded Astro/React components:

```mdx
---
layout: '@shared/layouts/BaseLayout.astro'
title: "My Post"
---

# Hello from MDX

<MyComponent />
```