API Reference

API Reference

This document provides a complete reference for the Astro Modular theme APIs and utilities.

Content Collections

Posts Collection

interface PostData {
  title: string;
  description: string;
  date: Date;
  tags?: string[];
  draft?: boolean;
  image?: string;
  imageAlt?: string;
  hideCoverImage?: boolean;
  targetKeyword?: string;
}

Projects Collection

interface ProjectData {
  title: string;
  description: string;
  date: Date;
  technologies?: string[];
  repositoryUrl?: string;
  demoUrl?: string;
  status: 'in-progress' | 'completed';
  image?: string;
  imageAlt?: string;
  hideCoverImage?: boolean;
  draft?: boolean;
}

Documentation Collection

interface DocumentationData {
  title: string;
  description: string;
  category: string;
  order: number;
  lastModified?: Date;
  version?: string;
  image?: string;
  imageAlt?: string;
  hideCoverImage?: boolean;
  draft?: boolean;
}

Utility Functions

SEO Generation

// Generate SEO data for posts
generatePostSEO(post: Post, url: string): SEOData

// Generate SEO data for projects
generateProjectSEO(project: Project, url: string): SEOData

// Generate SEO data for documentation
generateDocumentationSEO(doc: Documentation, url: string): SEOData

Markdown Processing

// Process markdown content
processMarkdown(content: string): {
  excerpt: string;
  wordCount: number;
  hasMore: boolean;
}

// Calculate reading time
calculateReadingTime(content: string): ReadingTime

// Generate table of contents
generateTOC(headings: Heading[]): Heading[]

Image Optimization

// Optimize post image paths
optimizePostImagePath(image: string, slug: string, id?: string): string

// Get fallback OG image
getFallbackOGImage(): OpenGraphImage

Configuration API

Site Configuration

interface SiteConfig {
  site: string;
  title: string;
  description: string;
  author: string;
  language: string;
  theme: ThemeName;
  features: FeatureConfig;
  navigation: NavigationConfig;
  // ... other options
}

Feature Configuration

interface FeatureConfig {
  readingTime: boolean;
  wordCount: boolean;
  tableOfContents: boolean;
  tags: boolean;
  linkedMentions: boolean;
  showCoverImages: CoverImageOption;
  postCardAspectRatio: AspectRatio;
  // ... other features
}

Component Props

PostCard Component

interface PostCardProps {
  post: Post | Project | Documentation;
  eager?: boolean;
  showCoverImage?: CoverImageOption;
  aspectRatio?: AspectRatio;
  customAspectRatio?: string;
}

TableOfContents Component

interface TableOfContentsProps {
  headings: Heading[];
}

Type Definitions

Core Types

interface Heading {
  depth: number;
  slug: string;
  text: string;
}

interface ReadingTime {
  text: string;
  minutes: number;
  time: number;
  words: number;
}

interface SEOData {
  title: string;
  description: string;
  canonical: string;
  ogImage?: OpenGraphImage;
  ogType: 'website' | 'article';
  // ... other SEO fields
}

Error Handling

Development Mode

• Graceful fallbacks for missing images
• Detailed error logging
• Continue processing with warnings

Production Mode

• Strict validation
• Build failures for missing assets
• Optimized error handling

Performance Considerations

Image Loading

• Lazy loading for below-the-fold images
• Eager loading for above-the-fold content
• WebP format priority
• Responsive image generation

Search Performance

• Debounced search input
• Cached search results
• Virtual scrolling for large lists
• Fuse.js fuzzy search integration