@astro-minimax/cli 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Souloss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @astro-minimax/cli
+
+CLI tool to scaffold a new blog project using the astro-minimax theme.
+
+## Usage
+
+```bash
+# npx (recommended)
+npx @astro-minimax/cli my-blog
+
+# pnpm
+pnpm dlx @astro-minimax/cli my-blog
+
+# yarn
+yarn dlx @astro-minimax/cli my-blog
+```
+
+## Generated Structure
+
+```
+my-blog/
+├── astro.config.ts      # Astro + minimax integration config
+├── package.json         # Dependencies (core, viz, tailwind, etc.)
+├── tsconfig.json        # TypeScript configuration
+├── public/
+│   └── favicon.svg
+└── src/
+    ├── config.ts        # SITE configuration object
+    ├── constants.ts     # Social links and share links
+    ├── content.config.ts # Astro content collection schema
+    ├── env.d.ts
+    └── data/
+        ├── blog/zh/hello-world.md   # Sample blog post
+        └── friends.ts               # Friend links data
+```
+
+No `src/pages/` directory — all routes are injected by `@astro-minimax/core`.
+
+## After Scaffolding
+
+1. **Install dependencies:**
+
+   ```bash
+   cd my-blog && pnpm install
+   ```
+
+2. **Configure your site** in `src/config.ts`:
+   - Set `website`, `author`, `title`, `desc`
+   - Configure features (tags, categories, series, etc.)
+
+3. **Start development:**
+
+   ```bash
+   pnpm dev
+   ```
+
+4. **Add blog posts** in `src/data/blog/zh/` (Chinese) or `src/data/blog/en/` (English).
+
+## Features
+
+### Built-in Features
+
+| Feature    | Description                 | Default |
+| ---------- | --------------------------- | ------- |
+| Tags       | Tag-based article filtering | Enabled |
+| Categories | Category-based navigation   | Enabled |
+| Series     | Article series grouping     | Enabled |
+| Archives   | Time-based article archive  | Enabled |
+| Search     | Full-text search (Pagefind) | Enabled |
+| Dark Mode  | Light/dark theme toggle     | Enabled |
+
+### Content Enhancements
+
+| Feature | Syntax               | Description                               |
+| ------- | -------------------- | ----------------------------------------- |
+| Mermaid | ` ```mermaid `       | Flowcharts, sequence diagrams, pie charts |
+| Markmap | ` ```markmap `       | Interactive mind maps                     |
+| Math    | `$...$` or `$$...$$` | KaTeX math equations                      |
+| Code    | ` ```language `      | Shiki syntax highlighting                 |
+| Emoji   | `:emoji_name:`       | Emoji shortcodes                          |
+| Alerts  | `> [!NOTE]`          | GitHub-style alerts                       |
+| Tables  | Markdown tables      | Styled responsive tables                  |
+
+## Customization
+
+- **Colors**: Override CSS custom properties in your own CSS file
+- **Features**: Toggle features in `SITE.features`
+- **Visualizations**: Use mermaid/markmap code blocks in Markdown
+
+## AI Chat Setup
+
+The template includes Preact integration ready for AI features.
+
+### Step 1: Install AI Package
+
+```bash
+pnpm add @astro-minimax/ai
+```
+
+### Step 2: Enable in Config
+
+Update `src/config.ts`:
+
+```typescript
+features: {
+  ai: true,  // Enable AI feature flag
+},
+
+ai: {
+  enabled: true,
+  mockMode: false,
+  apiEndpoint: "/api/chat",
+},
+```
+
+### Step 3: Create API Endpoint
+
+Create `functions/api/chat.ts`:
+
+```typescript
+import { handleChatRequest, initializeMetadata } from '@astro-minimax/ai/server';
+
+export const onRequest: PagesFunction = async (context) => {
+  initializeMetadata({}, context.env);
+  return handleChatRequest({ env: context.env, request: context.request });
+};
+```
+
+### Step 4: Configure Environment
+
+Create `.env` file:
+
+```env
+# OpenAI-compatible API
+AI_BASE_URL=https://api.openai.com/v1
+AI_API_KEY=your-api-key
+AI_MODEL=gpt-4o-mini
+
+# Or use Cloudflare Workers AI (in wrangler.toml)
+# [ai]
+# binding = "AI"
+```
+
+### Step 5: Run Dev Server
+
+For local development with AI:
+
+```bash
+# Start AI dev server (port 8787)
+node dev-ai-server.mjs
+
+# In another terminal, start Astro dev
+pnpm dev
+```
+
+The AI widget will appear as a floating button on your blog.
+
+## Optional Packages
+
+| Package             | Purpose                  |
+| ------------------- | ------------------------ |
+| `@astro-minimax/ai` | AI chat assistant widget |
+
+## Related Articles
+
+- [快速开始：两种使用方式](https://demo-astro-minimax.souloss.cn/zh/posts/getting-started)
+- [如何在 Astro 博客文章中添加 LaTeX 公式](https://demo-astro-minimax.souloss.cn/zh/posts/add-latex-to-astro-blog)
+- [如何使用 Git 钩子设置创建和修改日期](https://demo-astro-minimax.souloss.cn/zh/posts/git-hooks-for-date)
+- [如何更新 astro-minimax 的依赖](https://demo-astro-minimax.souloss.cn/zh/posts/update-dependencies)
+- [在 astro-minimax 中动态生成 OG 图片](https://demo-astro-minimax.souloss.cn/zh/posts/dynamic-og-image)

package/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { cpSync, mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const templateDir = join(__dirname, "template");
+
+const projectName = process.argv[2];
+if (!projectName) {
+  console.error("Usage: astro-minimax <project-name>");
+  console.error("       npx @astro-minimax/cli <project-name>");
+  process.exit(1);
+}
+
+const targetDir = resolve(process.cwd(), projectName);
+
+if (existsSync(targetDir)) {
+  console.error(`Directory "${projectName}" already exists.`);
+  process.exit(1);
+}
+
+mkdirSync(targetDir, { recursive: true });
+cpSync(templateDir, targetDir, { recursive: true });
+
+const pkgPath = join(targetDir, "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+pkg.name = basename(targetDir);
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+
+console.log(`\n  ✅ Created "${projectName}" successfully!\n`);
+console.log("  Next steps:\n");
+console.log(`    cd ${projectName}`);
+console.log("    pnpm install");
+console.log("    pnpm dev\n");
+console.log("  Docs: https://github.com/souloss/astro-minimax\n");

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@astro-minimax/cli",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "CLI tool to create a new astro-minimax blog project — a minimalist, fast, and modern Astro blog theme with AI-powered features.",
+  "author": "Souloss",
+  "license": "MIT",
+  "keywords": [
+    "astro",
+    "scaffold",
+    "cli",
+    "template",
+    "blog-starter",
+    "create-app"
+  ],
+  "homepage": "https://github.com/souloss/astro-minimax#readme",
+  "bugs": {
+    "url": "https://github.com/souloss/astro-minimax/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/souloss/astro-minimax",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "astro-minimax": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template/"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "astro": "^5.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.12.0",
+    "pnpm": ">=9.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/template/.env.example

@@ -0,0 +1,53 @@
+# ─────────────────────────────────────────────────────────────
+# Workers AI Configuration (Recommended for Cloudflare deployment)
+# ─────────────────────────────────────────────────────────────
+AI_BINDING_NAME=minimaxAI
+AI_WORKERS_MODEL=@cf/zai-org/glm-4.7-flash
+
+# ─────────────────────────────────────────────────────────────
+# OpenAI-Compatible API (For local dev or non-Cloudflare deployment)
+# ─────────────────────────────────────────────────────────────
+AI_API_KEY=your_api_key
+AI_BASE_URL=https://api.openai.com/v1
+AI_MODEL=gpt-4o-mini
+
+# ─────────────────────────────────────────────────────────────
+# AI Response Cache (Optional - Reduces API costs)
+# ─────────────────────────────────────────────────────────────
+AI_RESPONSE_CACHE_ENABLED=false
+AI_RESPONSE_CACHE_TTL=7200
+AI_RESPONSE_CACHE_PLAYBACK_DELAY=20
+AI_RESPONSE_CACHE_CHUNK_SIZE=15
+AI_RESPONSE_CACHE_THINKING_DELAY=5
+
+# ─────────────────────────────────────────────────────────────
+# Site Configuration
+# ─────────────────────────────────────────────────────────────
+SITE_URL=https://your-domain.com
+SITE_AUTHOR=Your Name
+SITE_DESCRIPTION=Your blog description
+
+# ─────────────────────────────────────────────────────────────
+# Notification - Telegram Provider (Optional)
+# Get token from @BotFather, chat ID from @userinfobot
+# ─────────────────────────────────────────────────────────────
+# NOTIFY_TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
+# NOTIFY_TELEGRAM_CHAT_ID=123456789
+
+# ─────────────────────────────────────────────────────────────
+# Notification - Email Provider via Resend (Optional)
+# Sign up at https://resend.com
+# ─────────────────────────────────────────────────────────────
+# NOTIFY_RESEND_API_KEY=re_xxxxxxxxxx
+# NOTIFY_RESEND_FROM=noreply@yourdomain.com
+# NOTIFY_RESEND_TO=you@example.com
+
+# ─────────────────────────────────────────────────────────────
+# Notification - Webhook (Optional)
+# ─────────────────────────────────────────────────────────────
+# NOTIFY_WEBHOOK_URL=https://your-webhook.com/notify
+
+# ─────────────────────────────────────────────────────────────
+# SEO - Google Site Verification (Optional)
+# ─────────────────────────────────────────────────────────────
+# PUBLIC_GOOGLE_SITE_VERIFICATION=your-verification-code

package/template/astro.config.ts

@@ -0,0 +1,204 @@
+import { defineConfig, envField } from "astro/config";
+import tailwindcss from "@tailwindcss/vite";
+import minimax from "@astro-minimax/core";
+import minimaxViz from "@astro-minimax/viz";
+import sitemap from "@astrojs/sitemap";
+import mdx from "@astrojs/mdx";
+import preact from "@astrojs/preact";
+import remarkToc from "remark-toc";
+import remarkCollapse from "remark-collapse";
+import remarkMath from "remark-math";
+import remarkGithubAlerts from "remark-github-alerts";
+import remarkEmoji from "remark-emoji";
+import rehypeKatex from "rehype-katex";
+import { remarkReadingTime } from "@astro-minimax/core/plugins/remark-reading-time";
+import { remarkAddZoomable } from "@astro-minimax/core/plugins/remark-add-zoomable";
+import { rehypeExternalLinks } from "@astro-minimax/core/plugins/rehype-external-links";
+import { rehypeTableScroll } from "@astro-minimax/core/plugins/rehype-table-scroll";
+import { rehypeAutolinkHeadings } from "@astro-minimax/core/plugins/rehype-autolink-headings";
+import {
+  transformerNotationDiff,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+} from "@shikijs/transformers";
+import {
+  updateStyle,
+  addTitle,
+  addLanguage,
+  addCopyButton,
+  addCollapse,
+} from "@astro-minimax/core/plugins/shiki-transformers";
+import { SITE } from "./src/config";
+import { SOCIALS, SHARE_LINKS } from "./src/constants";
+import { FRIENDS } from "./src/data/friends";
+
+const asTransformer = (t: unknown) => t;
+
+const shikiTransformers = [
+  asTransformer(updateStyle()),
+  asTransformer(addTitle()),
+  asTransformer(addLanguage()),
+  asTransformer(addCopyButton(2000)),
+  asTransformer(addCollapse(15)),
+  transformerNotationHighlight(),
+  transformerNotationWordHighlight(),
+  transformerNotationDiff({ matchAlgorithm: "v3" }),
+];
+
+export default defineConfig({
+  site: SITE.website,
+  output: "static",
+  prefetch: {
+    prefetchAll: true,
+    defaultStrategy: "hover",
+  },
+  integrations: [
+    minimax({
+      site: SITE,
+      socials: SOCIALS,
+      shareLinks: SHARE_LINKS,
+      friends: FRIENDS,
+      blogPath: "src/data/blog",
+    }),
+    minimaxViz({ mermaid: true, markmap: true }),
+    preact({ compat: true }),
+    sitemap({
+      filter: page => SITE.showArchives || !page.endsWith("/archives"),
+    }),
+    mdx({
+      shikiConfig: {
+        themes: { light: "github-light", dark: "night-owl" },
+        defaultColor: false,
+        wrap: false,
+        transformers: shikiTransformers,
+      },
+    }),
+  ],
+  markdown: {
+    remarkPlugins: [
+      remarkToc,
+      [remarkCollapse, { test: "Table of contents" }],
+      remarkMath,
+      remarkGithubAlerts,
+      remarkEmoji,
+      remarkReadingTime,
+      [remarkAddZoomable, { className: "zoomable" }],
+    ],
+    rehypePlugins: [
+      rehypeKatex,
+      rehypeExternalLinks,
+      rehypeTableScroll,
+      rehypeAutolinkHeadings,
+    ],
+    shikiConfig: {
+      themes: { light: "github-light", dark: "night-owl" },
+      defaultColor: false,
+      wrap: false,
+      transformers: shikiTransformers,
+    },
+  },
+  vite: {
+    plugins: [
+      tailwindcss() as never,
+      {
+        name: "astro-minimax-preact-singleton",
+        enforce: "pre" as const,
+        async resolveId(source, importer, options) {
+          if (source.startsWith("@/components/media")) {
+            const vizDir = new URL("../../packages/viz/src/components", import.meta.url).pathname;
+            return this.resolve(source.replace("@/components/media", vizDir), importer, { ...options, skipSelf: true });
+          }
+        },
+      },
+    ],
+    server: {
+      fs: {
+        strict: true,
+        allow: [
+          new URL("../../packages", import.meta.url).pathname,
+          new URL("../../node_modules", import.meta.url).pathname,
+          "./src",
+          "./.astro",
+        ],
+      },
+      proxy: {
+        "/api": {
+          target: `http://localhost:${process.env.AI_DEV_PORT || "8787"}`,
+          changeOrigin: true,
+        },
+      },
+    },
+    resolve: {
+      alias: {
+        "@/components/media": new URL("../../packages/viz/src/components", import.meta.url).pathname,
+        "@/" : new URL("./src/", import.meta.url).pathname,
+        "react": "preact/compat",
+        "react-dom": "preact/compat",
+        "react/jsx-runtime": "preact/jsx-runtime",
+      },
+      dedupe: ["preact", "preact/hooks", "preact/compat", "preact/debug", "preact/devtools", "react", "react-dom"],
+    },
+    optimizeDeps: {
+      exclude: ["@resvg/resvg-js"],
+      include: [
+        "preact",
+        "preact/hooks",
+        "preact/compat",
+        "preact/debug",
+        "preact/devtools",
+        "preact/jsx-runtime",
+        "preact/jsx-dev-runtime",
+        "@ai-sdk/react",
+        "ai",
+        "@astro-minimax/ai",
+        "@astro-minimax/core",
+        "@astro-minimax/viz",
+      ],
+    },
+    ssr: {
+      external: ["@resvg/resvg-js", "sharp"],
+      noExternal: [
+        "@astro-minimax/ai",
+        "@astro-minimax/core",
+        "@astro-minimax/viz",
+        "@ai-sdk/react",
+        "ai",
+      ],
+    },
+    build: {
+      rollupOptions: {
+        external: [/@resvg\/resvg-js/, /@resvg\/resvg-js-linux-.*/, /\.node$/],
+      },
+      cssMinify: true,
+      minify: "esbuild",
+      sourcemap: false,
+      reportCompressedSize: true,
+    },
+    environments: {
+      client: {
+        build: {
+          rollupOptions: {
+            output: {
+              chunkFileNames: "assets/[name]-[hash].js",
+              entryFileNames: "assets/[name]-[hash].js",
+              assetFileNames: "assets/[name]-[hash].[ext]",
+            },
+          },
+        },
+      },
+    },
+  },
+  image: {
+    responsiveStyles: true,
+    layout: "constrained",
+  },
+  env: {
+    schema: {
+      PUBLIC_GOOGLE_SITE_VERIFICATION: envField.string({
+        access: "public",
+        context: "client",
+        optional: true,
+      }),
+    },
+  },
+});

package/template/datas/ai-summaries.json

@@ -0,0 +1,8 @@
+{
+  "meta": {
+    "lastUpdated": "2026-01-01T00:00:00.000Z",
+    "model": "none",
+    "totalProcessed": 0
+  },
+  "articles": {}
+}

package/template/datas/author-context.json

@@ -0,0 +1,4 @@
+{
+  "author": {},
+  "posts": []
+}

package/template/datas/sources/blog-digest.json

@@ -0,0 +1,5 @@
+{
+  "generatedAt": "",
+  "count": 0,
+  "posts": []
+}

package/template/datas/voice-profile.json

@@ -0,0 +1,4 @@
+{
+  "style": {},
+  "examples": []
+}

package/template/eslint.config.js

@@ -0,0 +1,19 @@
+import eslintPluginAstro from "eslint-plugin-astro";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default [
+  ...tseslint.configs.recommended,
+  ...eslintPluginAstro.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+  },
+  { rules: { "no-console": "error" } },
+  { files: ["tools/**"], rules: { "no-console": "off" } },
+  { ignores: ["dist/**", ".astro/**", "public/pagefind/**"] },
+];

package/template/functions/api/ai-info.ts

@@ -0,0 +1,39 @@
+/// <reference types="@cloudflare/workers-types" />
+import { ProviderManager, hasAnyProviderConfigured, DEFAULT_WORKERS_BINDING_NAME } from '@astro-minimax/ai';
+import { initializeMetadata } from '@astro-minimax/ai/server';
+import type { ChatHandlerEnv } from '@astro-minimax/ai/server';
+import aiSummaries from '../../datas/ai-summaries.json';
+import authorContext from '../../datas/author-context.json';
+import voiceProfile from '../../datas/voice-profile.json';
+
+interface FunctionEnv extends ChatHandlerEnv {
+  [key: string]: unknown;
+}
+
+export const onRequest: PagesFunction<FunctionEnv> = async (context) => {
+  const env = context.env;
+  initializeMetadata(
+    { summaries: aiSummaries, authorContext, voiceProfile },
+    env,
+  );
+
+  const manager = new ProviderManager(env, { enableMockFallback: true });
+  const providerStatus = manager.getProviderStatus();
+  const bindingName = (env.AI_BINDING_NAME as string) || DEFAULT_WORKERS_BINDING_NAME;
+
+  return new Response(JSON.stringify({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    ai: {
+      configured: hasAnyProviderConfigured(env) || !!(env as Record<string, unknown>)[bindingName],
+      providers: providerStatus.map(p => ({
+        id: p.id, type: p.type, weight: p.weight, healthy: p.health.healthy, model: p.model,
+      })),
+    },
+    hints: manager.hasProviders()
+      ? [`Providers available: ${manager.getProviderCount()}`, 'Mock fallback: enabled']
+      : ['No AI providers configured. Set AI_BASE_URL + AI_API_KEY or configure Workers AI binding.'],
+  }, null, 2), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+};

package/template/functions/api/chat.ts

@@ -0,0 +1,20 @@
+/// <reference types="@cloudflare/workers-types" />
+import { handleChatRequest, initializeMetadata } from '@astro-minimax/ai/server';
+import type { ChatHandlerEnv } from '@astro-minimax/ai/server';
+import aiSummaries from '../../datas/ai-summaries.json';
+import authorContext from '../../datas/author-context.json';
+import voiceProfile from '../../datas/voice-profile.json';
+
+interface FunctionEnv extends ChatHandlerEnv {
+  CACHE_KV?: KVNamespace;
+  minimaxAI?: Ai;
+  [key: string]: unknown;
+}
+
+export const onRequest: PagesFunction<FunctionEnv> = async (context) => {
+  initializeMetadata(
+    { summaries: aiSummaries, authorContext, voiceProfile },
+    context.env,
+  );
+  return handleChatRequest({ env: context.env, request: context.request });
+};