astro-minimax Feature Overview

astro-minimax is a feature-rich Astro blog theme built with a modular architecture. This article provides a comprehensive overview of all features and how to use them.

Architecture Overview

astro-minimax consists of four core packages:

Content Management

Markdown / MDX

All posts are written in Markdown or MDX with support for:

• Standard Markdown syntax
• GFM (GitHub Flavored Markdown) extensions
• MDX component embedding
• Math equations (LaTeX via KaTeX)
• GitHub-style alerts (> [!NOTE], > [!WARNING], etc.)
• Emoji shortcodes (:smile: -> 😄)

Multi-language

Built-in Chinese/English bilingual support. Posts are organized by language:

src/data/blog/
├── zh/     # Chinese posts
└── en/     # English posts

Languages are distinguished by URL prefix: /zh/posts/... and /en/posts/....

Content Organization

Tags

Each post can have multiple tags for flexible cross-categorization:

tags:
  - astro
  - typescript
  - tutorial

The tags page (/tags/) displays a tag cloud. Click any tag to see all posts with that tag.

Categories

Hierarchical categories supported with / separators:

category: Tutorial/Configuration

The categories page (/categories/) displays a tree-structured category view.

Series

Organize related posts into ordered series:

series:
  name: Rust Getting Started
  order: 1

Series pages auto-generate navigation showing previous/next posts.

Archives

A timeline-based archive page (/archives/) showing all posts. Controlled by the features.archives toggle.

Frontmatter

Post metadata is defined via frontmatter:

---
title: Post Title
pubDatetime: 2026-03-14T10:00:00Z
modDatetime: 2026-03-20T01:46:35Z
author: Souloss
description: Post description
tags: [astro, tutorial]
category: Tutorial/Configuration
series: { name: "Series Name", order: 1 }
featured: true
draft: false
ogImage: ./cover.png
---

See Adding New Posts for details.

Cover Image

Two image fields in frontmatter serve different purposes:

• cover — Post cover image, shown on post cards and the article page banner
• ogImage — Social sharing image (Twitter, Facebook, etc.)

When cover is not set but ogImage is, the OG image is used as the cover. When neither is set, a dynamic OG image is auto-generated.

Search

Two search providers available, configurable via search.provider:

Pagefind Full-text Search (Default)

Built-in Pagefind static search engine:

• Search index generated at build time
• Fully static, no server required
• Chinese text segmentation support
• Search result highlighting
• Advanced filters (category, language, tags)

The search index is automatically generated during pnpm run build.

Algolia DocSearch

Support for Algolia DocSearch cloud search:

• Millisecond search response
• Ctrl+K keyboard shortcut to open search
• Search suggestions and autocomplete
• Search analytics and insights

Configuration:

search: {
  provider: 'docsearch',
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
  },
},

For a detailed comparison and setup walkthrough of both search providers, see the Search Configuration Guide.

Themes & Styling

Light/Dark Mode

Three theme modes supported:

• Light mode — White background, dark text
• Dark mode — Dark background, light text
• System — Automatically matches OS preference

Theme switching uses View Transitions animation for smooth transitions. Controlled by darkMode.

Custom Color Schemes

Customize the entire site’s colors through CSS variables:

:root {
  --background: #ffffff;
  --foreground: #1a1a2e;
  --accent: #3b82f6;
  --muted: #6b7280;
  --border: #e5e7eb;
}

[data-theme="dark"] {
  --background: #0f172a;
  --foreground: #e2e8f0;
  --accent: #60a5fa;
  --muted: #94a3b8;
  --border: #334155;
}

See Customizing Color Schemes for details.

Responsive Design

Mobile-first responsive design throughout:

• Mobile: Single-column layout, touch-friendly navigation
• Tablet: Optimized reading width
• Desktop: Full sidebar and floating TOC

Visualization Components

The @astro-minimax/core package provides rich visualization components.

Mermaid Diagrams

Write Mermaid diagrams directly in Markdown:

```mermaid
graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Execute]
  B -->|No| D[Skip]
```

Supports flowcharts, sequence diagrams, Gantt charts, pie charts, class diagrams, and all Mermaid chart types. Automatically adapts to light/dark themes.

Markmap Mind Maps

Generate interactive mind maps from Markdown outlines:

```markmap
# Central Topic
## Branch A
### Leaf 1
### Leaf 2
## Branch B
### Leaf 3
```

Supports zoom, pan, and expand/collapse interactions.

Rough.js Hand-drawn Graphics

Use hand-drawn style SVG shapes with the :::rough directive:

:::rough{config='{"width":400,"height":200,"shapes":[{"type":"rectangle","x":10,"y":10,"width":200,"height":100}]}'}

Excalidraw Whiteboard

Embed Excalidraw whiteboard-style diagrams with the :::excalidraw directive:

:::excalidraw{src="https://excalidraw.com/#json=..." height="500px"}

Automatically adapts to light/dark themes.

Asciinema Terminal Replay

Embed terminal recording playback with the :::asciinema directive:

:::asciinema{src="/casts/demo.cast" cols="120" rows="30"}

Markdown Directives

All visualization and media components are available as Markdown directives — no imports needed, works in both .md and .mdx files:

AI Chat

The @astro-minimax/ai package provides intelligent conversation capabilities.

Key Features

• Multi-provider support — Cloudflare Workers AI + OpenAI-compatible APIs
• Automatic failover — Seamlessly switches to backup when primary fails, Mock fallback guarantees availability
• Streaming responses — Real-time SSE streaming output
• RAG retrieval — Context-enhanced answers based on blog content
• Source priority protocol — L1-L5 source layers to prevent AI hallucination
• Intent classification — 7 topic categories for improved search relevance
• Privacy protection — Automatically refuses sensitive personal info queries (address, income, family, etc.)
• Reading companion — Article pages auto-inject context for contextual Q&A
• Global/session cache — Public questions cached across users for faster responses
• Mock mode — No real API needed during development
• AI tool calling — The assistant can control page UI directly: theme switching, article navigation, section scrolling, immersive mode, text highlighting
• Action executor system — Client-side action execution with cross-page action chaining and URL-based action persistence
• ChatPanel — Resizable panel with S/M/L presets
• CodeBlock — Enhanced visualization toolbar: zoom, fullscreen, copy

AI Tool Calling

The AI assistant has 7 built-in page interaction tools: toggleTheme, navigateToArticle, scrollToSection, toggleImmersiveMode, highlightText, setPreference, searchArticles. Users can switch themes, jump to articles, scroll to sections, and more without leaving the chat panel.

See the AI Tool Calling Guide for details.

Action System

A three-stage client-side pipeline: ActionExecutor + ActionQueue + URLHandler. Supports cross-page action chaining and URL-based action sharing. Encode action parameters into a URL, share it, and the recipient’s page executes the preset actions automatically. Combined with tool calling, it enables compound actions like “bookmark and navigate.”

See the AI Tool Calling Guide for details.

Usage

The AI chat appears as a floating widget in the bottom-right corner. Click to open the chat window where you can:

• Ask about blog content
• Get technical answers
• Browse blog navigation suggestions

Configuration

Enable in src/config.ts:

ai: {
  enabled: true,
  mockMode: false,       // Set to false for production
  apiEndpoint: "/api/chat",
},

See Configuration Guide for details.

Interactive Systems

Waline Comments

Built-in Waline comment system:

• Anonymous or authenticated comments
• Emoji pack support
• Page view counter
• Emoji reactions
• Comment word limit
• Markdown formatted comments

Requires self-hosted Waline server. See Configuration Guide.

Sponsorship

Donation feature supporting multiple payment methods:

• WeChat Pay
• Alipay
• Custom payment methods

Shows donation buttons and QR codes at the bottom of posts. Supports displaying a sponsors list.

Notification System

Multi-channel notifications to stay updated on blog activity:

• Telegram Bot: Receive comment and AI chat notifications
• Email (Resend): Email notifications
• Webhook: Custom notification channels

Rich notification content including token usage, phase timing, referenced articles, and automatic session ID anonymization for privacy.

See Notification System Configuration Guide for details.

SEO & Performance

Dynamic OG Images

Posts without a specified OG image get one auto-generated:

• Generated at build time as post-level social preview images
• Built from post title, author, and site information
• Custom font support
• 1200x640px dimensions

See Dynamic OG Images for details.

SEO Optimization

• Auto-generated sitemap.xml
• Auto-generated robots.txt
• RSS feed
• Semantic HTML structure
• Canonical URLs
• Structured data (JSON-LD)
• Correct Open Graph and Twitter Card tags

Performance

• Lighthouse 90+ target score
• Static site generation (zero server runtime)
• Automatic image optimization (Astro Image Service)
• Code splitting and lazy loading
• Preloading and prefetching
• CSS/JS minification
• Web Vitals monitoring

Code Enhancement

Syntax Highlighting

Shiki provides beautiful code highlighting:

• Dual theme support (light: github-light / dark: night-owl)
• Line highlighting / diff notation
• Code block title bar
• Language label
• One-click copy button
• Long code collapse/expand

Math Equations

LaTeX math equations rendered via KaTeX:

Inline: $E = mc^2$

Block:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

See How to Add LaTeX Equations for details.

Analytics

Umami

Integrated Umami privacy-friendly web analytics:

• No cookies
• GDPR compliant
• Lightweight (< 2KB)
• Self-hosted

Requires self-hosted Umami instance.

Additional Features

Feature Toggle Quick Reference

Control all feature toggles in features inside src/config.ts:

features: {
  tags: true,        // Tag system
  categories: true,  // Category system
  series: true,      // Series posts
  archives: true,    // Archives page
  friends: true,     // Friends page
  projects: true,    // Projects showcase
  search: true,      // Full-text search
},
darkMode: true,     // Light/dark theme

CLI Tools

The @astro-minimax/cli package provides a comprehensive command-line toolkit for blog management and AI content processing.

Installation

CLI tools are included with the @astro-minimax/cli package, or use npx astro-minimax for one-off commands.

Main Commands

Usage Examples

astro-minimax post new "Post Title"   # Create a new post
astro-minimax ai process               # AI process all articles
astro-minimax ai eval                  # Evaluate AI chat quality
astro-minimax ai profile build         # Build complete author profile
astro-minimax data status              # View data status

All commands also have pnpm run shortcuts (e.g. pnpm run ai:process). See CLI Guide.

AI Evaluation System

Built-in golden test set (datas/eval/gold-set.json) for automated AI chat quality assessment:

• 5 automated checks: non-empty, topic coverage, forbidden claims, link validation, answer mode
• Test against local dev server or production deployment
• Generates detailed report (datas/eval/report.json)

pnpm run ai:eval                                  # Local test
pnpm run ai:eval -- --url=https://your-blog.com   # Remote test

More Resources

• Getting Started — Installation & initial setup
• Configure Theme — Full configuration reference
• Add Posts — Post format & Frontmatter
• Deployment Guide — Multi-platform deployment
• Customize Colors — Theme color customization