diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..726018c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,156 @@ +# 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
+} +``` + +### 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 ` diff --git a/src/components/NotionBlocks.astro b/src/components/NotionBlocks.astro index 60e3210..30ae75f 100644 --- a/src/components/NotionBlocks.astro +++ b/src/components/NotionBlocks.astro @@ -1,18 +1,19 @@ --- +import type * as interfaces from '../lib/interfaces.ts' +import Bookmark from './notion/Bookmark.astro' import BulletedListItems from './notion/BulletedListItems.astro' import Callout from './notion/Callout.astro' import Code from './notion/Code.astro' import ColumnList from './notion/ColumnList.astro' import Divider from './notion/Divider.astro' -import Bookmark from './notion/Bookmark.astro' import Embed from './notion/Embed.astro' +import Equation from './notion/Equation.astro' import File from './notion/File.astro' import Heading1 from './notion/Heading1.astro' import Heading2 from './notion/Heading2.astro' import Heading3 from './notion/Heading3.astro' import Image from './notion/Image.astro' import LinkToPage from './notion/LinkToPage.astro' -import Equation from './notion/Equation.astro' import NumberedListItems from './notion/NumberedListItems.astro' import Paragraph from './notion/Paragraph.astro' import Quote from './notion/Quote.astro' @@ -22,7 +23,6 @@ import TableOfContents from './notion/TableOfContents.astro' import ToDo from './notion/ToDo.astro' import Toggle from './notion/Toggle.astro' import Video from './notion/Video.astro' -import type * as interfaces from '../lib/interfaces.ts' export interface Props { blocks: interfaces.Block[] @@ -52,19 +52,11 @@ const { return