blog-astro/AGENTS.md

AGENTS.md

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

Build & Development Commands

# 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:

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