# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Project Overview

This is a multi-blog Astro application that deploys 13 separate blog collections to individual subdomains on Netlify at `neeldhara.blog`. Each blog collection (art, bfs, dfs, problems, puzzles, reviews, reflections, vibes, workflows, magic, contests, poetry, and blog) has its own subdomain (e.g., `art.neeldhara.blog`) but is built from a single codebase.

The architecture is based on the Charter Astro Template and uses:
- Astro 5.x for static site generation
- Tailwind CSS 4 for styling
- React 19 for interactive components
- shadcn/ui components
- MDX for content with frontmatter

## Common Commands

### Development
```bash
npm install              # Install dependencies
npm run dev             # Start dev server at http://localhost:4321
npm run preview         # Preview production build locally
```

### Building
```bash
npm run build           # Build static site to dist/
npm run astro check     # Type check Astro files
```

### Formatting
```bash
npm run format          # Format code with Prettier
```

### Deployment
The site is deployed to Netlify with automatic builds on push. The `netlify.toml` configuration handles all subdomain routing. See `DEPLOYMENT.md` for details.

## Architecture

### Content Collections
All blog content is managed through Astro Content Collections in `src/content/config.ts`. Each collection (art, bfs, dfs, etc.) has:
- Its own directory in `src/content/[collection-name]/`
- Shared schema with required fields: `title`, `description`, `pubDate`, and optional `updatedDate`, `image`, `authorImage`, `authorName`
- Supports both `.md` and `.mdx` files

### Routing Structure
The site uses file-based routing with a consistent pattern across all collections:
- `src/pages/[collection]/index.astro` - Collection homepage
- `src/pages/[collection]/[...slug].astro` - Individual blog posts
- `src/pages/[collection]/rss.xml.js` - RSS feed per collection

Global pages include:
- `src/pages/index.astro` - Main landing page
- `src/pages/latest.astro` - Aggregated latest posts from all collections
- `src/pages/about.astro` - About page
- Other utility pages: 404, contact, faq, login, signup, privacy, terms

### Subdomain Deployment
All 13 collections are built into a single static site, but Netlify redirects handle subdomain routing:
- Each subdomain (e.g., `art.neeldhara.blog`) rewrites to the main domain path (`/art/*`)
- Static assets (`_astro/*`, `assets/*`) are shared across all subdomains
- Special redirects prevent double-path issues (e.g., `/art/art/slug` → `/art/slug`)
- Global pages (`/latest`, `/about`) redirect from subdomains to the main domain

### Component Organization
```
src/components/
├── BaseHead.astro         # Common <head> tags
├── elements/              # Small reusable elements (header links, theme toggle)
├── icons/                 # Icon components
├── problems/              # Interactive components for problem posts
├── sections/              # Page sections (navbar, footer, blog-post, etc.)
└── ui/                    # shadcn/ui components (button, card, tabs, etc.)
```

### TypeScript Configuration
- Path aliases configured in `tsconfig.json`:
  - `@/*` → `./src/*`
  - `@components/*` → `./src/components/*`
  - `@layouts/*` → `./src/layouts/*`
  - `@lib/*` → `./src/lib/*`
- Strict mode enabled with React JSX support

### Styling
- Tailwind CSS 4 configured via Vite plugin in `astro.config.mjs`
- Global styles in `src/styles/global.css`
- Prettier with tailwindcss plugin for class sorting

## Adding a New Blog Collection

To add a new blog collection:

1. Create content directory: `src/content/[collection-name]/`
2. Add collection definition in `src/content/config.ts`:
   ```typescript
   const newCollection = defineCollection({
     loader: glob({ base: "./src/content/newCollection", pattern: "**/*.{md,mdx}" }),
     schema: blogSchema,
   });
   ```
3. Export in collections object
4. Create page structure in `src/pages/[collection-name]/`:
   - `index.astro` (list view)
   - `[...slug].astro` (single post view)
   - `rss.xml.js` (RSS feed)
5. Add subdomain redirects in `netlify.toml` following existing patterns
6. Configure subdomain DNS in Netlify dashboard

## Key Files

- `astro.config.mjs` - Astro configuration with MDX, sitemap, React integrations
- `netlify.toml` - Subdomain routing and redirect configuration
- `src/content/config.ts` - Content collection definitions
- `src/consts.ts` - Site metadata and global constants
- `DEPLOYMENT.md` - Subdomain deployment documentation

## Interactive Components

Some blog posts (especially in the `problems` collection) include interactive React components for visualizations. These are stored in `src/components/problems/` and imported directly into MDX files. Use `client:only="react"` directive for React components that require browser APIs.

## Content Frontmatter Example

```mdx
---
title: "Post Title"
description: "Post description for SEO and preview"
pubDate: 2025-01-15
updatedDate: 2025-01-20
image: "/images/post-image.jpg"
authorName: "Author Name"
authorImage: "/images/author.jpg"
---

Post content here...
```
