astro-minimax 0.8.0

astro-minimax is a minimal, responsive, accessible and SEO-friendly Astro blog theme. This project is built on top of AstroPaper and has evolved through multiple versions into a fully-featured independent theme. Current version 0.8.0 is built on Astro v6.

Project Origins

astro-minimax originated from deep customization and feature expansion of the AstroPaper theme. While preserving the minimal, high-performance, and accessible nature of the original, we’ve added numerous practical features making it more suitable for Chinese users and modern blogging needs.

Core Features

🚀 Framework Evolution

🎨 Unique Features

astro-minimax adds the following features on top of AstroPaper:

AI & Interaction

• 🤖 AI Chat Widget - Built-in AI assistant with streaming responses
• 💬 Waline Comments - Full-featured comment system with reactions and notifications

Content Enhancement

• 📊 Mermaid Diagrams - Native support for flowcharts, sequence diagrams, Gantt charts, etc.
• 🧠 Markmap Mind Maps - Interactive mind maps from Markdown outline syntax
• 🎬 Bilibili Embeds - One-click Bilibili video embedding
• 📑 Dual TOC - Inline and floating table of contents

Visualization Components

• ✏️ Rough.js Drawings - Hand-drawn style SVG graphics with theme-aware colors
• 🖌️ Excalidraw Embeds - Whiteboard-style collaborative diagrams
• 📦 VizContainer - Unified wrapper with zoom controls and fullscreen support for all visual components

i18n & Organization

• 🌐 Multi-language - Built-in Chinese/English support
• 🏷️ Categories & Series - Hierarchical content organization
• 📖 Related Posts - Smart recommendation algorithm
• 🔗 Friends Page - Friend links management

Social & Sponsorship

• ☕ Sponsor Component - Support WeChat Pay, Alipay, and other donation methods
• ©️ Copyright Notice - Automatic CC license display
• 🔗 Share Links - One-click sharing to social platforms

User Experience

• ⏰ Scheduled Posts - Time-based publication control
• 🌍 Timezone Support - Global and per-post timezone settings
• 📍 Reading Position - Persistent scroll position memory
• 🎨 Theme Switching - Improved light/dark mode transitions with all components reactively updating
• 📖 Series Navigation - Redesigned series index and detail pages with better visual hierarchy
• 🗂️ Projects Page - Dedicated page to showcase project portfolio
• ⚙️ Config-Driven Navigation - Header navigation items configurable via config.ts

Developer Tools

• 🛠️ AI Toolchain - Build-time tools for summary generation, tag suggestion, cover image generation, content vectorization
• 🧮 Vector Search - Semantic search based on TF-IDF / OpenAI Embeddings

🔧 Tech Stack

Core Framework

• Astro v6 - Modern static site generator
• TypeScript - Type safety
• TailwindCSS v4 - Atomic CSS

Feature Integration

• Pagefind - Static full-text search
• Waline - Comment system
• Mermaid - Diagram rendering
• Rough.js - Hand-drawn style graphics
• Shiki - Code highlighting

Deployment & Analytics

• Vercel / Cloudflare Pages - Deployment platforms
• Umami - Privacy-friendly traffic analytics

Version Evolution Summary

Base Architecture (Inherited from AstroPaper)

• Type-safe Content Management - Type-safe Markdown frontmatter via Content Collections API
• View Transitions - Page transition animations for better UX
• Dynamic OG Images - Auto-generated social sharing images
• Responsive Design - Mobile-first, adapts to all screen sizes
• SEO Optimization - JSON-LD structured data, sitemap, RSS feed

Performance Optimizations

• Removed React Dependency - Replaced Fuse.js with Pagefind, reducing bundle size
• Tailwind v4 - Faster builds, smaller CSS output
• Astro SVG Component - Experimental SVG component, less boilerplate
• pnpm Package Manager - More efficient dependency management

Project Structure

/
├── src/
│   ├── components/
│   │   ├── ai/          # AI chat widget
│   │   ├── blog/        # Post components, TOC, comments, copyright
│   │   ├── media/       # Mermaid, Markmap, Rough.js, Excalidraw
│   │   ├── nav/         # Header, footer, pagination, floating actions
│   │   ├── social/      # Sponsorship, social links
│   │   └── ui/          # Cards, tags, alerts, timeline, collapse
│   ├── data/
│   │   ├── blog/        # Blog posts (en/, zh/)
│   │   ├── vectors/     # Vector index (for AI search)
│   │   └── friends.ts   # Friend links data
│   ├── pages/
│   │   └── [lang]/      # Multi-language routes
│   ├── config.ts        # Site configuration
│   └── constants.ts     # Constants definition
├── tools/               # AI toolchain
│   ├── lib/             # Shared utilities
│   ├── summarize.ts     # Summary generation
│   ├── generate-tags.ts # Tag suggestion
│   ├── generate-cover.ts# Cover image generation
│   ├── generate-related.ts # Related posts
│   └── vectorize.ts     # Content vectorization
└── public/
    └── pagefind/        # Search index

Quick Start

# Create project from template
pnpm create astro@latest --template souloss/astro-minimax

# Install dependencies
pnpm install

# Start development server
pnpm run dev

Acknowledgements

astro-minimax wouldn’t exist without the support of these projects and individuals:

• AstroPaper - Original theme by Sat Naing
• Astro - Excellent static site framework
• All contributors and users for their support

Roadmap

astro-minimax will continue to evolve. Future plans include:

• 🤖 More AI feature integrations
• 📱 PWA support
• 🎨 More preset themes
• 📊 Advanced data visualization with D3.js integration

Thank you for choosing astro-minimax! If you like it, please consider giving a GitHub Star ⭐

Souloss - Creator of astro-minimax