知识库（Wiki）搭建

知识库适合发布成体系的文档或教程，支持层级目录、侧边栏导航和封面页，类似 Wiki 或在线文档。

文件位置

知识库存放在 src/content/docs/ 目录下，使用 Markdown 格式（.md）。

创建知识库

在 src/content/docs/ 下新建一个目录，目录名即知识库的标识：

src/content/docs/└── my-tutorial/           ← 知识库目录    ├── _meta.md           ← 知识库元信息    ├── index.md           ← 封面页    ├── getting-started.md ← 第一章    └── advanced/          ← 子目录        └── config.md      ← 子章节

src/content/docs/
└── my-tutorial/           ← 知识库目录
    ├── _meta.md           ← 知识库元信息
    ├── index.md           ← 封面页
    ├── getting-started.md ← 第一章
    └── advanced/          ← 子目录
        └── config.md      ← 子章节

_meta.md — 知识库元信息

每个知识库需要一个 _meta.md 文件，填写基本信息：

---
title: 我的教程
description: 从零开始学习搭建博客
order: 1
cover: '@img/docs/my-guide/cover.jpg'
dirs:
  - getting-started
  - advanced
---

字段	必填	说明
`title`	是	知识库标题
`subtitle`	否	知识库副标题
`description`	否	知识库描述
`icon`	否	知识库图标（Lucide kebab-case 图标名）
`order`	否	排序权重，数字越小越靠前
`excerpt`	否	知识库摘要，列表页预览文字
`cover`	否	知识库列表页卡片封面图，使用 Astro 图片优化，放在 `src/assets/img/docs/<知识库>/`，用 `@img/` 引用
`banner`	否	知识库文章详情页顶部横幅，支持完整 URL 或关键词（触发 Unsplash 随机图）
`autoRender`	否	封面页是否自动列出子目录文章，`true`（默认）或 `false`
`dirs`	否	子目录结构，控制侧边栏层级和顺序
`homepage`	否	指定封面页展示的文章，见下方说明
`splash`	否	封面页（开屏页）配置，见下方说明

普通文档

知识库中的普通文档：

---
title: 安装与启动
order: 1
---

## 环境要求

...

## 安装步骤

...

字段	必填	说明
`title`	是	文档标题
`order`	否	在侧边栏中的排序位置

知识库列表页

访问 /docs/ 可查看所有知识库的列表。每个知识库以卡片形式呈现，包含封面图、标题和描述。

封面页

知识库可以设置一个封面页（splash），作为进入知识库的第一个页面：

---
title: 我的教程
splash:
  enabled: true
  backgroundImage: /images/splash-bg.jpg
  buttonText: 开始学习
---

封面页会显示大图背景、标题和一个”开始学习”按钮，点击后进入正文。

按钮的玻璃效果默认沿用站点开屏页的 glass 配置（见开屏页）。某个知识库想不一样，只写想改的项：

---
splash:
  enabled: true
  glass:
    nav: frosted   # 这个知识库的按钮用毛玻璃
---

指定首页文章

默认情况下，封面页展示的是知识库中第一篇文章的内容。你可以在_meta.md文件设置homepage 字段显式指定：

---
title: 我的教程
homepage: getting-started
splash:
  enabled: true
---

homepage 的值为文章文件路径（不含 .md 后缀），相对于知识库目录。例如：

homepage: getting-started → 使用 getting-started.md
homepage: advanced/config → 使用 advanced/config.md

指定后，该文章不会生成独立的页面链接，侧边栏中点击它会回到封面页。

自动渲染子目录（autoRender）

默认情况下，封面页（index.md）会自动列出当前知识库的所有子目录文章，方便读者快速浏览全部内容。

如果你希望封面页只展示自定义内容（而不是自动列出文章），关闭 autoRender：

---
title: 我的教程
autoRender: false
---

## 欢迎

这是我的自定义封面内容，不会自动列出子目录文章。

关闭后，读者只能通过侧边栏导航进入子章节。

使用建议

一个知识库聚焦一个主题，比如”Astro 入门教程”或”摄影后期指南”
用 order 控制章节顺序，让读者按正确的顺序阅读
子目录用 dirs 配置中文名称，侧边栏显示更友好