apex-accelerator astro.instructions.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://apexops.pro/
• Base path: /apex
• 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:

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

Admonitions

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

:::note[Title]
Content here
:::

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

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

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

Tabbed Content

Import Starlight components for tabs:

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:

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

Sidebar Configuration

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