136 lines
5.1 KiB
Markdown
136 lines
5.1 KiB
Markdown
# 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...
|
|
```
|