如何配置 astro-minimax 主题

astro-minimax 是一个高度可定制的 Astro 博客主题。使用 astro-minimax，你可以根据个人喜好定制一切。本文将解释如何通过配置文件轻松进行一些自定义设置。

Open Table of contents

配置 SITE
更新布局宽度
配置 Logo 或标题
配置社交链接
配置分享链接
配置 Waline 评论
配置 AI 聊天
配置赞助
配置版权声明
配置 Umami 统计
配置字体
- 使用默认字体
- 自定义字体
结语

配置 SITE

重要的配置位于 src/config.ts 文件中。在该文件中，你会看到 SITE 对象，可以在其中指定网站的主要配置。

在开发模式下，SITE.website 可以留空。但在生产模式下，你应该在 SITE.website 选项中指定你部署的 URL，因为这会用于规范 URL、社交卡片 URL 等，这些对 SEO 很重要。

export const SITE = {
  website: "https://demo-astro-minimax.souloss.cn/", // replace this with your deployed domain
  author: "Sat Naing",
  profile: "https://souloss.cn/",
  desc: "A minimal, responsive and SEO-friendly Astro blog theme.",
  title: "astro-minimax",
  ogImage: "astro-minimax-og.jpg",
  lightAndDarkMode: true,
  postPerIndex: 4,
  postPerPage: 4,
  scheduledPostMargin: 15 * 60 * 1000, // 15 minutes
  showArchives: true,
  showBackButton: true, // show back button in post detail
  editPost: {
    enabled: true,
    text: "Suggest Changes",
    url: "https://github.com/souloss/astro-minimax/edit/main/",
  },
  dynamicOgImage: true, // enable automatic dynamic og-image generation
  dir: "ltr", // "rtl" | "auto"
  lang: "en", // html lang code. Set this empty and default will be "en"
  timezone: "Asia/Bangkok", // Default global timezone (IANA format) https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
} as const;

以下是 SITE 配置选项说明

Options	Description
`website`	你部署的网站 URL
`author`	你的名字
`profile`	你的个人/作品集网站 URL，用于更好的 SEO。如果没有可以设置为 `null` 或空字符串 `""`。
`desc`	网站描述。对 SEO 和社交媒体分享很有用。
`title`	网站名称
`ogImage`	网站的默认 OG 图片。用于社交媒体分享。OG 图片可以是外部图片 URL，也可以放在 `/public` 目录下。
`lightAndDarkMode`	启用或禁用网站的 `明暗模式`。如果禁用，将使用主配色方案。此选项默认启用。
`postPerIndex`	首页 `最近文章` 部分显示的文章数量。
`postPerPage`	指定每个文章页面显示的文章数量。（例如：如果将 `SITE.postPerPage` 设为 3，每页将只显示 3 篇文章）
`scheduledPostMargin`	在生产模式下，`pubDatetime` 为未来的文章将不可见。但如果文章的 `pubDatetime` 在未来 15 分钟内，它将可见。如果你不喜欢默认的 15 分钟边距，可以设置 `scheduledPostMargin`。
`showArchives`	决定是否显示 `归档` 菜单（位于 `关于` 和 `搜索` 菜单之间）及其对应页面。此选项默认为 `true`。
`showBackButton`	决定是否在每篇博客文章中显示 `返回` 按钮。
`editPost`	此选项允许用户通过在博客文章标题下提供编辑链接来建议更改博客文章。可以通过将 `SITE.editPost.enabled` 设为 `false` 来禁用此功能。
`dynamicOgImage`	此选项控制当博客文章 frontmatter 中未指定 `ogImage` 时是否生成动态 og-image。如果你有很多博客文章，可能想要禁用此功能。详见权衡说明。
`dir`	指定整个博客的文本方向。用作 `<html dir="ltr">` 中的 HTML dir 属性。支持的值：`ltr` \| `rtl` \| `auto`
`lang`	用作 `<html lang"en">` 中的 HTML ISO 语言代码。默认为 `en`。
`timezone`	此选项允许你使用 IANA 格式指定时区。设置此选项可确保本地主机和部署站点的时间戳一致，消除时间差异。

更新布局宽度

整个博客的默认 max-width 是 768px（max-w-3xl）。如果你想更改它，可以轻松更新 global.css 中的 max-w-app 工具类。例如：

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

css

你可以在 Tailwind CSS 文档中探索更多 max-width 值。

配置 Logo 或标题

在 astro-minimax v5 之前，你可以在 src/config.ts 文件的 LOGO_IMAGE 对象中更新网站名称/logo。但在 astro-minimax v5 中，此选项已被移除，改用 Astro 内置的 SVG 和 Image 组件。

你有 3 种选择：

选项 1：SITE 标题文本

这是最简单的选项。只需在 src/config.ts 文件中更新 SITE.title。

选项 2：Astro 的 SVG 组件

如果你想使用 SVG logo，可以使用此选项。

首先在 src/assets 目录中添加 SVG。（例如：src/assets/dummy-logo.svg）

然后在 Header.astro 中导入该 SVG

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

astro

最后，用导入的 logo 替换 {SITE.title}。

<a
  href="/"
  class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
>
  <DummyLogo class="scale-75 dark:invert" />
  <!-- {SITE.title} -->
</a>

html

这种方法的最大优点是可以根据需要自定义 SVG 样式。在上面的示例中，你可以看到 SVG logo 颜色如何在深色模式下反转。

选项 3：Astro 的 Image 组件

如果你的 logo 是图片但不是 SVG，可以使用 Astro 的 Image 组件。

在 src/assets 目录中添加 logo。（例如：src/assets/dummy-logo.png）

在 Header.astro 中导入 Image 和你的 logo

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

astro

然后，用导入的 logo 替换 {SITE.title}。

<a
  href="/"
  class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
>
  <Image src="{dummyLogo}" alt="Dummy Blog" class="dark:invert" />
  <!-- {SITE.title} -->
</a>

html

使用这种方法，你仍然可以使用 CSS 类调整图片外观。但这可能并不总是符合你的需求。如果需要根据明暗模式显示不同的 logo 图片，请查看 Header.astro 组件中明暗图标是如何处理的。

配置社交链接

An arrow pointing at social link icons

你可以在 constants.ts 的 SOCIALS 对象中配置社交链接。

export const SOCIALS = [
  {
    name: "GitHub",
    href: "https://github.com/souloss/astro-minimax",
    linkTitle: ` ${SITE.title} on GitHub`,
    icon: IconGitHub,
  },
  {
    name: "X",
    href: "https://x.com/username",
    linkTitle: `${SITE.title} on X`,
    icon: IconBrandX,
  },
  {
    name: "LinkedIn",
    href: "https://www.linkedin.com/in/username/",
    linkTitle: `${SITE.title} on LinkedIn`,
    icon: IconLinkedin,
  },
  {
    name: "Mail",
    href: "mailto:yourmail@gmail.com",
    linkTitle: `Send an email to ${SITE.title}`,
    icon: IconMail,
  },
] as const;

配置分享链接

你可以在 src/constants.ts 的 SHARE_LINKS 对象中配置分享链接。

An arrow pointing at share link icons

配置 Waline 评论

astro-minimax 内置 Waline 评论系统。在 src/config.ts 的 SITE.waline 中配置：

waline: {
  enabled: true,
  serverURL: "https://your-waline-server.vercel.app/",
  emoji: [
    "//unpkg.com/@waline/emojis@1.2.0/weibo",
    "//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"],
},

选项	说明
`enabled`	是否启用评论系统
`serverURL`	Waline 服务端地址
`emoji`	表情包配置
`lang`	评论组件语言
`pageview`	是否显示页面浏览量
`reaction`	是否启用表情互动
`login`	登录模式：`enable` / `disable` / `force`

配置 AI 聊天

astro-minimax 内置 AI 聊天助手。在 SITE.ai 中配置：

ai: {
  enabled: true,
  apiEndpoint: "",
  apiKey: "",
  model: "gpt-4o-mini",
  maxTokens: 1024,
  systemPrompt: "你是一个技术博客的 AI 助手...",
  mockMode: true,
  vectorSearch: true,
},

选项	说明
`enabled`	是否启用 AI 聊天
`mockMode`	Mock 模式下不调用真实 API，返回预设回复
`vectorSearch`	是否基于向量索引检索相关内容回答问题
`apiEndpoint`	自定义 API 端点（兼容 OpenAI 接口）
`model`	使用的模型名称

配置赞助

在 SITE.sponsor 中配置打赏功能：

sponsor: {
  enabled: true,
  methods: [
    { name: "微信支付", icon: "wechat", image: "/images/wechat-pay.svg" },
    { name: "支付宝", icon: "alipay", image: "/images/alipay.svg" },
  ],
  sponsors: [],
},

将你的收款码图片放到 public/images/ 目录下即可。

配置版权声明

在 SITE.copyright 中配置版权协议：

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

配置 Umami 统计

在 SITE.umami 中配置 Umami 访问统计：

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

配置字体

astro-minimax 使用 Astro 的实验性字体 API，默认字体为 Google Sans Code。这提供了跨所有平台的一致排版，并自动进行字体优化，包括预加载和缓存。

使用默认字体

字体在 astro.config.ts 中自动配置，并在 Layout.astro 中加载。使用默认的 Google Sans Code 字体无需额外配置。

自定义字体

要使用不同的字体，需要更新三个地方：

更新 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"],
      },
    ],
  },
});

更新 Layout.astro 中的 Font 组件：

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

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

astro

更新 global.css 中的 CSS 变量映射：

@theme inline {
  --font-app: var(--font-your-font); 
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-accent: var(--accent);
  --color-muted: var(--muted);
  --color-border: var(--border);
}

css

--font-app 变量通过 font-app Tailwind 工具类在整个主题中使用，因此更新此单个变量将在所有地方应用你的自定义字体。

注意：确保字体名称与 Google Fonts 上显示的完全一致。对于其他字体提供商或本地字体，请参阅 Astro 实验性字体 API 文档。

结语

这是关于如何自定义此主题的简要说明。如果你懂一些代码，可以进行更多自定义。关于自定义样式，请阅读这篇文章。感谢阅读。✌🏻

如何配置 astro-minimax 主题

Table of contents

配置 SITE

更新布局宽度

配置 Logo 或标题

选项 1：SITE 标题文本

选项 2：Astro 的 SVG 组件

选项 3：Astro 的 Image 组件

配置社交链接

配置分享链接

配置 Waline 评论

配置 AI 聊天

配置赞助

配置版权声明

配置 Umami 统计

配置字体

使用默认字体

自定义字体

结语

相关推荐

快速开始：两种使用方式

自定义 astro-minimax 主题配色方案

在 astro-minimax 主题中添加新文章

评论区