---
description: "Astro Starlight development standards for the documentation site"
applyTo: "site/**/*.astro, site/**/*.ts, site/**/*.mjs, site/**/*.mdx, site/**/*.md"
---

# Astro Starlight Documentation Site

Standards for the `site/` Astro Starlight documentation project.

## Project Context

- Astro 6.x with `@astrojs/starlight` — static docs site (SSG only, no SSR)
- Site URL: `https://jonathan-vella.github.io/azure-agentic-infraops/`
- Base path: `/azure-agentic-infraops`
- Trailing slashes: always (`trailingSlash: "always"`)
- TypeScript for type safety with auto-generated types
- Content-driven documentation using Starlight content collections
- Mermaid diagram support via `rehype-mermaid-lite` (client-side rendering)

## Architecture

- Use `.astro` components for static, server-rendered content
- Import framework components only when client-side interactivity is required
- Use `client:load` for interactive components (e.g., D3 architecture explorer)
- Use `client:idle` for non-critical interactive components
- Follow Islands Architecture: server-first, hydrate selectively

## Content Conventions

### Frontmatter

Every content page must include:

```yaml
---
title: "Page Title"
description: "Brief page description for SEO"
sidebar:
  order: 1
---
```

### Admonitions

Use Starlight's remark directive syntax (NOT MkDocs `!!!` syntax):

```markdown
:::note[Title]
Content here
:::

:::tip[Title]
Content here
:::

:::caution[Title]
Content here
:::

:::danger[Title]
Content here
:::
```

### Tabbed Content

Import Starlight components for tabs:

```mdx
import { Tabs, TabItem } from "@astrojs/starlight/components";

<Tabs>
  <TabItem label="Bicep">Content</TabItem>
  <TabItem label="Terraform">Content</TabItem>
</Tabs>
```

### Code Blocks

Use Astro Expressive Code features:

- Language after triple backticks: ` ```bicep `
- Title: ` ```bicep title="main.bicep" `
- Line highlighting: ` ```bicep {3-5} `
- Copy button: included by default

### Mermaid Diagrams

Use fenced code blocks with `mermaid` language — rendered client-side by `rehype-mermaid-lite`:

````markdown
```mermaid
graph LR
  A --> B
```
````

## Sidebar Configuration

Use `autogenerate` for directory-based sections. Override with manual entries only when explicit ordering is needed:

```javascript
sidebar: [
  { label: "Getting Started", autogenerate: { directory: "getting-started" } },
  { label: "Concepts", autogenerate: { directory: "concepts" } },
];
```

Control page order within autogenerated sections via frontmatter `sidebar.order`.

## Custom CSS

Theme overrides in `src/styles/custom.css` use Starlight CSS custom properties:

- `--sl-color-accent`: Azure blue `#0078d4`
- `--sl-font`: body font (Manrope)
- `--font-display`: heading font (Space Grotesk)
- `--font-mono`: code font (IBM Plex Mono)

Reference via `customCss` in `astro.config.mjs`.

## TypeScript

- Config extends `astro/tsconfigs/base`
- Types auto-generated in `.astro/types.d.ts`
- Run `astro sync` to regenerate types after schema changes
- Define component props with TypeScript interfaces

## Build & Development

```bash
cd site
npm run dev      # Dev server with hot reload
npm run build    # Production build to dist/
npm run preview  # Preview production build
```

## Key Constraints

- **No SSR**: This is a static documentation site — do not enable SSR mode
- **No API routes**: No `src/pages/api/` — this is a content-only site
- **Base path**: All asset references must account for `/azure-agentic-infraops/` base
- **Edit links**: Point to `https://github.com/jonathan-vella/azure-agentic-infraops/edit/main/site/`
- **Pagefind search**: Built-in with Starlight — no additional config needed
