Blogs/blogs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
blogs/WARP.md

5.1 KiB
Raw Blame History

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

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

Building

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

Formatting

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

---
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...