blog-astro/AGENTS.md

# AGENTS.md

This file provides guidelines for agentic coding assistants working on this Astro blog repository.

## Build & Development Commands

```bash
# Development server (runs on port 1234)
bun run dev    # or bun run start

# Production build
bun run build

# Preview production build
bun run preview

# Format code (uses Prettier with Astro plugins)
bun run prettier

# Install dependencies
bun install

# Apply patches after install (runs automatically via postinstall)
patch-package
```

**Testing**: No test framework is currently configured in this project.

## Tech Stack

- **Framework**: Astro 5.7.13 (SSR mode, output: 'server')
- **UI**: React 19.0.0 via @astrojs/react
- **Styling**: Tailwind CSS v4.1.7 via @tailwindcss/vite
- **TypeScript**: 5.8.3 with strict mode enabled
- **Content**: Notion API integration for blog posts
- **UI Components**: shadcn/ui (new-york style, neutral base color)
- **Code Blocks**: astro-expressive-code with collapsible sections
- **Math/Code**: KaTeX for math, rehype-pretty-code for syntax highlighting

## Code Style Guidelines

### Formatting (Prettier)
- Single quotes (`'`), no semicolons, trailing comma (es5 style)
- Plugins: `prettier-plugin-astro`, `prettier-plugin-tailwindcss`, `prettier-plugin-astro-organize-imports`
- Format with: `bun run prettier`

### TypeScript Configuration
- Strict mode enabled (`strictNullChecks: true`)
- Path aliases: `@/*` → `./src/*`
- JSX: `react-jsx` with React as import source

### Imports
- Use path alias `@/` for all internal imports:
  - `@/components/*` → components
  - `@/lib/*` → utility functions
  - `@/styles/*` → stylesheets
- External imports: named imports preferred
- React components: `import { Button } from '@/components/ui/button'`
- Astro components: `import Header from '@/components/Header.astro'`

### Component Patterns

**Astro Components (.astro)**:
- Use for main layout and content components
- Props interface defined in frontmatter: `export interface Props { ... }`
- Use `class` prop for CSS classes (not `className`)
- Extract props: `const { class: className } = Astro.props`

**React Components (.tsx)**:
- Use for interactive UI components (shadcn/ui pattern)
- Use `className` for CSS classes
- Use `cn()` utility for conditional class merging
- Radix UI primitives for accessibility
- class-variance-authority (cva) for component variants

**Example:**
```tsx
import { cn } from '@/lib/utils'
import { cva } from 'class-variance-authority'

const variants = cva('base-classes', {
  variants: { variant: { default: '...', outline: '...' } }
})

function Component({ className, variant, ...props }) {
  return <div className={cn(variants({ variant }), className)} {...props} />
}
```

### Styling

**Tailwind CSS**:
- Primary styling framework (v4, no config file)
- Use `cn()` from `@/lib/utils` for merging conditional classes
- Dark mode via `data-theme` attribute (not media query)
- CSS variables defined in `src/styles/global.css` for theming
- OKLCH color space for all colors

**CSS Variables**:
- Light mode: `:root` selector
- Dark mode: `[data-theme='dark']` selector
- Semantic tokens: `--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--ring`
- Special tokens: `--notion-surface`, `--notion-border`, `--fg`, `--anchor-border`

**Custom CSS**:
- `global.css`: Main stylesheet with Tailwind imports
- `notion-color.css`: Notion integration colors
- `typography.css`: Text styling
- `syntax-coloring.css`: Code highlighting styles

### Type Definitions
- All shared types in `src/lib/interfaces.ts`
- Notion API types: Block, Paragraph, Heading1-3, Image, Code, etc.
- Use explicit types for all props and function parameters

### Utility Functions
- `cn()` from `@/lib/utils`: Merge CSS classes (clsx + tailwind-merge)
- `formatDate()`, `readingTime()`, `calculateWordCountFromHtml()` in `@/lib/utils`
- Blog helpers in `@/lib/blog-helpers.ts`: URL parsing, slug generation, Notion image handling
- Style helpers in `@/lib/style-helpers.ts`: CSS class transformations

### Component Structure
- Layouts: `src/layouts/Layout.astro`
- Pages: `src/pages/*.astro` and `src/pages/**/*.astro`
- Components: `src/components/*.astro` and `src/components/ui/*.tsx`
- Notion block components: `src/components/notion/*.astro`

### Naming Conventions
- Components: PascalCase (`Header.astro`, `Button.tsx`)
- Files: PascalCase for components, kebab-case for utilities
- CSS classes: Tailwind utilities, custom classes in kebab-case
- Functions: camelCase (`cn()`, `formatDate()`)
- Constants: UPPER_SNAKE_CASE (`SITE`, `ENABLE_LIGHTBOX`)

### Error Handling
- Use try-catch for async operations
- Console errors for image URL parsing failures
- Graceful null/undefined checks for optional properties
- Return early for invalid data: `if (!block.Paragraph) return null`

### Inline Scripts
- Use `is:inline` for client-side scripts that need to execute immediately
- Use standard `<script>` tags for scoped client-side logic
- Listen to Astro events: `astro:after-swap` for navigation updates

### Content Pattern (Notion Integration)
- Blog posts fetched from Notion API
- Block-based rendering: `NotionBlocks.astro` recursively renders block arrays
- Each block type has a dedicated component (`Paragraph.astro`, `Heading1.astro`, etc.)
- Rich text rendering via `RichText.astro` for text formatting
- Children blocks supported for nested content

### Deployment
- Vercel adapter configured (`adapter: vercel()`)
- SSR output mode
- Server-side rendering for all pages