How to configure astro-minimax theme

astro-minimax is a highly customizable Astro blog theme. With astro-minimax, you can customize everything according to your personal taste. This article will explain how you can make some customizations easily in the config file.

Path note: If you’re using the GitHub Template method, the config file is at apps/blog/src/config.ts. For NPM package integration, it’s at src/config.ts in your project root.

Configuring SITE

The main configuration resides in the SITE object in src/config.ts. Here’s the full configuration example:

export const SITE = {
  website: "https://your-domain.com/",
  author: "Your Name",
  profile: "https://your-portfolio.com/",
  desc: "A minimal, responsive and SEO-friendly Astro blog theme.",
  title: "My Blog",
  ogImage: "astro-minimax-og.jpg",
  postPerIndex: 4,
  postPerPage: 4,
  scheduledPostMargin: 15 * 60 * 1000,
  showBackButton: true,
  startDate: "2020-01-01",
  editPost: {
    enabled: true,
    text: "Edit page",
    url: "https://github.com/your-user/your-repo/edit/main/",
  },
  dynamicOgImage: true,
  dir: "ltr",
  lang: "en",
  timezone: "Asia/Shanghai",

  features: {
    tags: true,
    categories: true,
    series: true,
    archives: true,
    friends: true,
    projects: true,
    search: true,
  },

  darkMode: true,
};

Basic Configuration

Edit Link Configuration

editPost: {
  enabled: true,
  text: "Edit page",
  url: "https://github.com/your-user/your-repo/edit/main/",
},

Configuring Feature Toggles

The features object controls which feature modules are enabled or disabled:

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 page
  search: true,      // Full-text search (Pagefind)
},

Dark Mode

darkMode: true,    // Light/dark theme toggle

Disabling dark mode will hide the theme toggle button in the UI.

AI Chat

AI chat is controlled by SITE.ai.enabled. Enable the @astro-minimax/ai package first, then configure:

ai: {
  enabled: true,
  mockMode: true,
  apiEndpoint: "/api/chat",
  model: "@cf/zai-org/glm-4.7-flash",
},

Waline Comments

Waline comments are controlled by SITE.waline.enabled:

waline: {
  enabled: true,
  serverURL: "https://your-waline-server.vercel.app/",
  // ...
},

Sponsorship

Sponsorship is controlled by SITE.sponsor.enabled:

sponsor: {
  enabled: true,
  methods: [
    { name: "WeChat Pay", icon: "wechat", image: "/images/wechat-pay.svg" },
    { name: "Alipay", icon: "alipay", image: "/images/alipay.svg" },
  ],
  sponsors: [],
},

Disabling a feature will automatically hide the corresponding menu item and page.

Configuring Navigation Menu

The nav object controls which menu items appear in the navigation bar:

nav: {
  items: [
    { key: "home", enabled: true },
    { key: "posts", enabled: true },
    { key: "tags", enabled: true },
    { key: "categories", enabled: true },
    { key: "series", enabled: true },
    { key: "projects", enabled: true },
    { key: "about", enabled: true },
    { key: "friends", enabled: true },
    { key: "archives", enabled: true },
  ],
},

Set enabled: false to hide specific menu items. Menu visibility is also affected by features toggles — if a feature is disabled, its menu item is automatically hidden too.

Configuring Projects

List your GitHub projects in SITE.projects:

projects: [
  { repo: "souloss/astro-minimax", featured: true },
  { repo: "withastro/astro" },
  { repo: "your-user/your-project", description: "Custom description" },
],

Update layout width

The default max-width for the entire blog is 768px (max-w-3xl). If you’d like to change it, update the max-w-app utility in global.css:

@utility max-w-app {
  @apply max-w-3xl;
  @apply max-w-4xl xl:max-w-5xl;
}

You can explore more max-width values in the Tailwind CSS docs.

Configuring logo or title

Option 1: SITE title text

The easiest option. Just update SITE.title.

Option 2: Astro’s SVG component

For SVG logos:

• Add an SVG file in src/assets directory
• Import and replace the title text in Header.astro

---
import DummyLogo from "@/assets/dummy-logo.svg";
---

<a href="/" class="...">
  <DummyLogo class="scale-75 dark:invert" />
</a>

Option 3: Astro’s Image component

For bitmap logos (non-SVG):

---
import { Image } from "astro:assets";
import dummyLogo from "@/assets/dummy-logo.png";
---

<a href="/" class="...">
  <Image src={dummyLogo} alt="My Blog" class="dark:invert" />
</a>

Configuring social links

Configure social links in SOCIALS inside src/constants.ts:

import IconGitHub from "@/assets/icons/IconGitHub.svg";
import IconBrandX from "@/assets/icons/IconBrandX.svg";
import IconMail from "@/assets/icons/IconMail.svg";

export const SOCIALS = [
  {
    name: "GitHub",
    href: "https://github.com/your-username",
    linkTitle: "My Blog on GitHub",
    icon: IconGitHub,
  },
  {
    name: "X",
    href: "https://x.com/your-username",
    linkTitle: "My Blog on X",
    icon: IconBrandX,
  },
  {
    name: "Mail",
    href: "mailto:your@email.com",
    linkTitle: "Send me an email",
    icon: IconMail,
  },
];

Available built-in icons: IconGitHub, IconBrandX, IconLinkedin, IconFacebook, IconTelegram, IconMail, IconWhatsapp, IconPinterest, IconRss.

Configuring share links

Configure post share buttons in SHARE_LINKS inside src/constants.ts:

export const SHARE_LINKS = [
  {
    name: "X",
    href: "https://x.com/intent/post?url=",
    linkTitle: "Share on X",
    icon: IconBrandX,
  },
  // ...
];

Configuring Waline Comments

astro-minimax comes with a built-in Waline comment system. Configure it in SITE.waline:

waline: {
  enabled: true,
  serverURL: "https://your-waline-server.vercel.app/",
  emoji: [
    "https://unpkg.com/@waline/emojis@1.2.0/weibo",
    "https://unpkg.com/@waline/emojis@1.2.0/bilibili",
  ],
  lang: "zh-CN",
  pageview: true,
  reaction: true,
  login: "enable",
  wordLimit: [0, 1000],
  imageUploader: false,
  requiredMeta: ["nick", "mail"],
  copyright: true,
  recaptchaV3Key: "",
  turnstileKey: "",
},

You need to deploy a Waline server first. See the Waline documentation.

Configuring Search

astro-minimax supports two search providers. Pagefind is used by default with no extra configuration.

Pagefind (Default)

Built-in static search engine. Search index is auto-generated at build time. Works out of the box.

Algolia DocSearch

To use Algolia DocSearch cloud search, configure SITE.search:

search: {
  provider: 'docsearch',
  docsearch: {
    appId: 'YOUR_ALGOLIA_APP_ID',
    apiKey: 'YOUR_ALGOLIA_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    placeholder: 'Search docs...',
  },
},

DocSearch requires applying or self-hosting an Algolia index. When enabled, the DocSearch button replaces the default Pagefind search link in the header.

Configuring AI Chat

astro-minimax includes a built-in AI chat assistant powered by @astro-minimax/ai. Configure it in SITE.ai:

ai: {
  enabled: true,
  mockMode: true,
  apiEndpoint: "/api/chat",
  model: "@cf/zai-org/glm-4.7-flash",
  welcomeMessage: undefined,
  placeholder: undefined,
},

The AI chat feature uses Cloudflare Pages Functions as the backend. Deployment on Cloudflare with AI Binding configuration is required. See the apps/blog/functions/ directory and wrangler.toml for details.

Configuring Sponsorship

Configure donation/tip features in SITE.sponsor:

sponsor: {
  enabled: true,
  methods: [
    { name: "WeChat Pay", icon: "wechat", image: "/images/wechat-pay.svg" },
    { name: "Alipay", icon: "alipay", image: "/images/alipay.svg" },
  ],
  sponsors: [
    { name: "John", amount: 50, date: "2026-01-15" },
  ],
},

Place payment QR code images in the public/images/ directory.

Configuring Copyright

Configure the copyright license in SITE.copyright:

copyright: {
  license: "CC BY-NC-SA 4.0",
  licenseUrl: "https://creativecommons.org/licenses/by-nc-sa/4.0/",
},

Configuring Umami Analytics

Configure Umami privacy-friendly analytics in SITE.umami:

umami: {
  enabled: false,
  websiteId: "your-website-id",
  src: "https://your-umami-instance.com/script.js",
},

You need to deploy a Umami instance first. See the Umami documentation.

Configuring fonts

astro-minimax uses Astro’s experimental fonts API with Google Sans Code as the default font.

Customizing the font

To use a different font, update three places:

1. Font configuration in astro.config.ts:

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  experimental: {
    fonts: [
      {
        name: "Your Font Name",
        cssVariable: "--font-your-font",
        provider: fontProviders.google(),
        fallbacks: ["monospace"],
        weights: [300, 400, 500, 600, 700],
        styles: ["normal", "italic"],
      },
    ],
  },
});

2. Font component in Layout.astro:

---
import { Font } from "astro:assets";
---

<head>
  <Font
    cssVariable="--font-your-font"
    preload={[{ subset: "latin", weight: 400, style: "normal" }]}
  />
</head>

3. CSS variable in global.css:

@theme inline {
  --font-app: var(--font-your-font);
}

The --font-app variable is used throughout the theme via the font-app Tailwind utility class.

Conclusion

This is the full specification of how to customize this theme. For a complete feature overview, see the Feature Overview.