Skip to content

CLAUDE.md

Latest commit

 

History

History
242 lines (200 loc) · 10.5 KB

CLAUDE.md

File metadata and controls

242 lines (200 loc) · 10.5 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a comprehensive tag-based blog built with Astro and Tailwind CSS using pnpm as the package manager. The blog features a complete component system, responsive layouts, dark mode support, and modern typography for an optimal reading experience. All components are server-side rendered Astro components with minimal client-side JavaScript only where needed.

Common Commands

You should not run development server or build command.

  • pnpm astro ... - Run Astro CLI commands (e.g., pnpm astro add, pnpm astro check)

Architecture

  • Framework: Astro v5 with TypeScript strict mode
  • Components: Pure Astro components for all UI elements (Header, Footer, PostCard, TagPill)
  • Styling: Tailwind CSS v4 with Vite plugin for optimal utility-first styling and Tailwind Typography plugin
  • Package Manager: pnpm (required, specified in packageManager field)
  • Blog Type: Tag-based content organization with collections
  • Theme: Dark mode support throughout all components
  • Typography: Tailwind Typography plugin v4 with CSS custom properties for theme customization and optimal blog content readability
  • Responsive Design: Mobile-first approach with breakpoint-specific designs

File Structure

src/
├── components/           # Astro components for UI elements
│   ├── Header.astro     # Responsive navigation with mobile menu
│   ├── Footer.astro     # Three-column footer with links and social
│   ├── PostCard.astro   # Blog post preview cards
│   └── TagPill.astro    # Consistent tag display component
├── layouts/             # Astro layouts for page structure
│   ├── BaseLayout.astro # Base HTML structure and meta tags
│   └── BlogLayout.astro # Blog post layout with metadata and sharing
├── pages/               # File-based routing pages
│   └── index.astro      # Homepage with hero, featured posts, tags
├── content/             # Content collections
│   ├── blog/           # Blog post markdown files
│   └── config.ts       # Content collection schemas
├── styles/             # Global styles and typography
│   └── global.css      # Tailwind Typography customizations and global styles
└── public/             # Static assets (favicon.svg, images)

Component System

Core Astro Components

  1. Header.astro

    • Responsive navigation with collapsible mobile menu
    • Dark mode styling support
    • Navigation links: Home, Posts, Tags, About
    • Mobile hamburger menu with vanilla JavaScript for interaction
    • Accessible ARIA labels and keyboard navigation
    • Server-side rendered with minimal client-side JavaScript

  2. Footer.astro

    • Three-column responsive layout
    • Quick Links, Categories, and Social sections
    • Dark mode support with consistent styling
    • Social media icons and external links
    • Fully static component with no JavaScript required

  3. PostCard.astro

    • Blog post preview component with image support
    • Displays title, excerpt, publication date, author, reading time
    • Tag integration using TagPill component
    • Responsive image handling with fallback
    • Hover effects and interactive elements via CSS
    • Server-side rendered for optimal performance

  4. TagPill.astro

    • Consistent tag display across the site
    • Supports different sizes (small, medium, large)
    • Interactive hover states via CSS
    • Links to tag-specific pages
    • Lightweight static component

Layout Components

  1. BaseLayout.astro

    • HTML document structure and meta tags
    • SEO optimization with title, description, Open Graph
    • Includes Header and Footer components
    • Dark mode class handling

  2. BlogLayout.astro

    • Specialized layout for individual blog posts
    • Hero image support with responsive sizing
    • Article metadata display (author, date, reading time)
    • Tag integration in header and footer
    • Social sharing buttons (Twitter, LinkedIn)
    • Tailwind Typography plugin with prose classes (prose prose-gray dark:prose-invert prose-lg)
    • "Back to posts" navigation

Content Management

Blog Collection Schema (src/content/config.ts)

blog: {
  title: string,           # Post title
  description: string,     # SEO description and excerpt
  tags: string[],         # Array of tags for categorization
  pubDate: Date,          # Publication date
  updatedDate?: Date,     # Optional update date
  draft?: boolean         # Draft status (defaults to false)
}

Content Organization

  • Blog Posts: Markdown files in src/content/blog/ directory
  • Tag System: Automatic tag-based categorization and filtering
  • Type Safety: Astro content collections provide full TypeScript support
  • Draft Support: Optional draft flag to hide unpublished content

Design System

Color Scheme

  • Light Mode: Gray-900 text on white backgrounds
  • Dark Mode: White/gray-300 text on gray-800/900 backgrounds
  • Accent Colors: Blue-600/400 for links and interactive elements
  • Borders: Gray-200/700 for subtle divisions

Typography (global.css)

  • Prose Styling: Tailwind Typography plugin v4 with CSS custom properties for theme customization
  • Theme Variables: Light and dark mode typography colors defined via CSS custom properties
  • Plugin Configuration: Uses @plugin "@tailwindcss/typography" syntax optimized for Tailwind v4
  • Built-in Utilities: Leverages Tailwind v4's improved built-in utilities (line-clamp, focus states)
  • Minimal Custom CSS: Reduced custom styling by utilizing v4's enhanced utility set
  • Responsive Design: Typography plugin handles responsive scaling automatically
  • Dark Mode Support: Complete theme variable overrides for dark mode prose styling
  • Code Styling: Enhanced inline code with background colors and padding
  • Print Styles: Optimized typography for print media

Tailwind Typography Implementation

The project uses Tailwind CSS v4 with the official Typography plugin for consistent, accessible prose styling:

/* Plugin import in global.css - v4 syntax */
@plugin "@tailwindcss/typography";

/* CSS Custom Properties for theme customization */
.prose {
  --tw-prose-body: theme(colors.gray.700);
  --tw-prose-headings: theme(colors.gray.900);
  --tw-prose-links: theme(colors.blue.600);
  /* ... additional theme variables ... */
  
  /* Dark mode overrides */
  &.dark, .dark & {
    --tw-prose-body: theme(colors.gray.300);
    --tw-prose-headings: theme(colors.white);
    --tw-prose-links: theme(colors.blue.400);
    /* ... dark mode theme variables ... */
  }
}

Usage in components: Apply prose prose-gray dark:prose-invert prose-lg max-w-none classes for consistent blog post styling.

v4 Improvements:

  • Enhanced tree-shaking reduces bundle size
  • Built-in line-clamp-2 and line-clamp-3 utilities replace custom implementations
  • Improved focus utilities eliminate need for custom focus ring styles
  • Better Vite integration with @tailwindcss/vite plugin

Responsive Breakpoints

  • Mobile First: Base styles for mobile devices
  • sm: 640px and up
  • md: 768px and up (navigation breakpoint)
  • lg: 1024px and up
  • xl: 1280px and up

Navigation Structure

Expected Pages

  • / - Homepage with hero, featured posts, popular tags
  • /posts - All blog posts listing
  • /tags - Tag overview page
  • /tags/[tag] - Posts filtered by specific tag
  • /posts/[slug] - Individual blog post pages
  • /about - About page

Navigation Patterns

  • Header Navigation: Main site navigation across all pages
  • Tag Navigation: Tag-based filtering throughout the site
  • Post Navigation: Previous/next post navigation in blog layout
  • Social Sharing: Twitter and LinkedIn sharing on blog posts

Development Guidelines

Component Conventions

  • Astro Components: Use TypeScript interfaces for props in frontmatter
  • Component Props: Define props interface in Astro frontmatter for type safety
  • Astro Layouts: Accept props interface for reusability
  • Styling: Prefer Tailwind v4 built-in utilities over custom CSS
  • Utility Usage: Leverage v4's enhanced utilities (line-clamp-*, improved focus states)
  • Interactivity: Use vanilla JavaScript in script tags for minimal client-side functionality
  • Typography: Use Tailwind Typography plugin v4 classes for content areas
  • Prose Styling: Apply prose prose-gray dark:prose-invert prose-lg for blog content
  • Theme Customization: Use CSS custom properties for typography theme overrides
  • Performance: Utilize v4's improved tree-shaking and purging capabilities
  • Accessibility: Include ARIA labels and semantic HTML
  • Dark Mode: Support both light and dark themes with automatic prose theme switching

Content Conventions

  • Images: Use descriptive alt text and responsive sizing
  • Tags: Use consistent lowercase formatting for URLs
  • Dates: Format dates consistently across components
  • SEO: Include proper meta tags and descriptions

Performance Considerations

  • Image Optimization: Use appropriate image sizes and formats
  • Server-Side Rendering: All components are server-rendered by default
  • Minimal JavaScript: Client-side JavaScript only used where absolutely necessary (mobile menu)
  • Static Generation: Astro pre-renders pages for optimal performance
  • CSS Optimization: Tailwind v4 enhanced tree-shaking and purging for smaller bundles
  • Vite Integration: Optimized @tailwindcss/vite plugin for faster builds and better performance
  • Built-in Utilities: v4's native utilities reduce custom CSS and improve maintainability
  • Typography Plugin: Leverages optimized Tailwind Typography plugin v4 for better performance
  • Theme Variables: CSS custom properties enable efficient dark mode switching without duplicate styles
  • Bundle Size: v4 improvements result in significantly smaller CSS bundles
  • Zero Runtime Overhead: Components ship zero JavaScript by default

Future Development

Planned Features

  • Search functionality across blog posts
  • Tag-based filtering and discovery pages
  • RSS feed generation
  • Comment system integration
  • Author profile pages
  • Related posts suggestions

Extensibility

  • Component system designed for easy extension
  • Content schema can be expanded with additional fields
  • Layout system supports multiple content types
  • Theme system ready for additional color schemes