首页配置

首页配置决定了网站首页的展示内容：每页显示多少篇文章、突出展示哪些分类。所有配置都在 src/theme.config.ts 的 home 字段中。

快速开始：最简配置

如果你刚开始使用主题，可以只配置这两项：

src/theme.config.ts

export default defineConfig({
  // ...
  home: {
    pageSize: 5,                    // 每页显示 5 篇文章
    selectedCategories: [           // 突出显示两个分类
      { name: "Tutorial" },
      { name: "Frontend" },
    ],
  },
});

效果：

• 首页和分页页面每页显示 5 篇普通文章（置顶文章不计入）
• 首页顶部会展示”Tutorial”和”Frontend”两个分类的卡片

提示

两个字段都是可选的。如果不配置 home，会使用默认值：pageSize: 10，不显示分类卡片。

配置文章数量（pageSize）

pageSize 控制每页显示多少篇文章。

默认值

如果不配置，默认每页显示 10 篇文章。

自定义数量

根据你的文章长度和首屏高度，调整合适的数量：

src/theme.config.ts

export default defineConfig({
  home: {
    pageSize: 8,  // 每页显示 8 篇
  },
});

置顶文章不占用配额

如果你的文章设置了 sticky: true（置顶），它们会优先显示在首页顶部，不占用 pageSize 的配额。

例如：

• 你有 3 篇置顶文章
• pageSize: 5
• 首页实际显示：3 篇置顶 + 5 篇普通 = 共 8 篇文章

关于置顶文章

置顶文章通过在文章 frontmatter 中设置 sticky: true 来实现，不在 theme.config.ts 中配置。

配置突出显示的分类（selectedCategories）

selectedCategories 用于在首页顶部展示特定分类的卡片，帮助访问者快速找到你的核心内容。

显示分类卡片

假设你的博客有”教程""前端""后端”等分类，你想突出展示”教程”和”前端”：

src/theme.config.ts

export default defineConfig({
  home: {
    selectedCategories: [
      { name: "Tutorial" },
      { name: "Frontend" },
    ],
  },
});

警告

name 必须与你文章中使用的分类名称完全一致（区分大小写）。

如何知道我有哪些分类？

分类来自文章 frontmatter 的 categories 字段。例如：

src/posts/my-post.md

---
title: 我的文章
categories:
  - Tutorial
  - Frontend
---

你可以查看 src/posts/ 目录下的文章，看看它们都使用了哪些分类名称。

不显示分类卡片

如果你不想在首页显示分类卡片，有两种方式：

方式 A：不配置 selectedCategories（推荐）

src/theme.config.ts

export default defineConfig({
  home: {
    pageSize: 5,
    // 不配置 selectedCategories
  },
});

方式 B：设为空数组

src/theme.config.ts

export default defineConfig({
  home: {
    selectedCategories: [],  // 明确不显示
  },
});

进阶：给分类设置封面图

你可以为每个分类卡片设置自定义封面图，让首页更有视觉冲击力：

src/theme.config.ts

export default defineConfig({
  home: {
    selectedCategories: [
      {
        name: "Tutorial",
        cover: "/images/tutorial-cover.jpg",  // public 路径
      },
      {
        name: "Frontend",
        cover: "https://example.com/frontend.jpg",  // 远程 URL
      },
    ],
  },
});

封面图的使用方式

• public 路径：把图片放到 public/images/ 目录，配置中填写 /images/xxx.jpg
• 远程 URL：直接填写完整的图片地址，如 https://...
• 不设置：分类卡片会使用默认渐变背景（非常美观，推荐保持默认）

推荐做法

如果你不确定用什么图片，保持默认样式就很好看，不需要刻意添加封面。

配置项速查

字段	类型	默认值	说明
pageSize	number	10	每页显示的文章数量（不含置顶文章）。
selectedCategories	Array	[]	首页突出显示的分类列表。
selectedCategories[].name	string	-	必填。分类名称（需与文章中一致）。
selectedCategories[].cover	string	-	可选。分类封面图片（public 路径或 URL）。

首页内容展示顺序

首页的完整展示顺序如下：

1. 置顶文章区（如果有）
2. 分类卡片区（如果配置了 selectedCategories）
3. 最新文章区（根据 pageSize 显示）
4. 分页导航（如果文章数量超过 pageSize）

注意

分类卡片和置顶文章只在首页（第一页）显示，后续分页页面（/page/2/ 等）只显示普通文章列表。

完整配置示例

一个典型的首页配置：

src/theme.config.ts

export default defineConfig({
  siteName: "我的博客",
  // ... 其他配置

  home: {
    pageSize: 6,
    selectedCategories: [
      { name: "教程" },
      { name: "前端开发" },
      { name: "随笔", cover: "/images/essay-cover.jpg" },
    ],
  },
});

常见问题

Q: 为什么配置了 selectedCategories，但首页不显示分类卡片？

检查以下几点：

1. 分类名称是否与文章中的分类完全一致（区分大小写、空格）
2. 该分类下是否有已发布的文章（draft: false 或未设置 draft）
3. 浏览器是否缓存了旧页面（尝试硬刷新 Ctrl+F5）

Q: 置顶文章太多，首页太长怎么办？

置顶文章会全部显示在首页顶部，建议控制在 3 篇以内。如果确实有很多重要文章需要突出，可以考虑：

• 只保留最重要的 2-3 篇置顶
• 其他文章通过分类卡片或精选标签来组织

Q: 可以设置不同页面使用不同的 pageSize 吗？

目前 pageSize 是全局配置，首页和所有分页页面使用相同的数量。如果需要更灵活的配置，需要修改 src/pages/index.astro 和 src/pages/page/[page].astro。