如何配置 AstroPaper 主题

AstroPaper 是一个高度可定制的 Astro 博客主题。使用 AstroPaper，你可以根据自己的个人喜好定制一切。本文将介绍如何在配置文件中轻松进行一些自定义设置。

Table of contents

配置 SITE

重要的配置都存放在 src/config.ts 文件中。在该文件中，你会看到 SITE 对象，可以在这里指定网站的主要配置。

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

export const SITE = {
  website: "https://astro-paper.pages.dev/", // 替换为你部署的域名
  author: "Sat Naing",
  profile: "https://satnaing.dev/",
  desc: "A minimal, responsive and SEO-friendly Astro blog theme.",
  title: "AstroPaper",
  ogImage: "astropaper-og.jpg",
  lightAndDarkMode: true,
  postPerIndex: 4,
  postPerPage: 4,
  scheduledPostMargin: 15 * 60 * 1000, // 15 分钟
  showArchives: true,
  showBackButton: true, // 在文章详情页显示返回按钮
  editPost: {
    enabled: true,
    text: "Suggest Changes",
    url: "https://github.com/satnaing/astro-paper/edit/main/",
  },
  dynamicOgImage: true, // 启用自动动态 og-image 生成
  dir: "ltr", // "rtl" | "auto"
  lang: "en", // html lang 代码。留空则默认为 "en"
  timezone: "Asia/Bangkok", // 默认全局时区（IANA 格式）
} as const;src/config.ts

SITE 配置选项说明

更新布局宽度

整个博客的默认最大宽度是 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;
}src/styles/global.css

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

配置 logo 或标题

在 AstroPaper v5 之前，你可以在 src/config.ts 文件的 LOGO_IMAGE 对象中更新网站名称/logo。然而，在 AstroPaper 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";
---src/components/Header.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>

这种方法最好的部分是你可以根据需要自定义 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";
---src/components/Header.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>

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

配置社交链接

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

export const SOCIALS = [
  {
    name: "GitHub",
    href: "https://github.com/satnaing/astro-paper",
    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

配置分享链接

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

配置字体

AstroPaper 使用 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"],
      },
    ],
  },
});astro.config.ts

更新 Layout.astro 中的 Font 组件：

---
import { Font } from "astro:assets";
// ...
---
<head>
  <!-- ... -->
  <Font
    cssVariable="--font-your-font"
    preload={[{ subset: "latin", weight: 400, style: "normal" }]}
  />
  <!-- ... -->
</head>src/layouts/Layout.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);
}src/styles/global.css

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

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

结语

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

感谢阅读！