输入关键词,开始搜索

↑↓ 选择↵ 打开esc 关闭
沉浸

知识库搭建

知识库(Wiki)搭建

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

文件位置

知识库存放在 src/content/docs/ 目录下,使用 Markdown 格式(.md)。

创建知识库

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

src/content/docs/└── my-tutorial/           ← 知识库目录    ├── _meta.md           ← 知识库元信息    ├── getting-started.md ← 第一章,默认就是知识库首页    └── advanced/          ← 子目录(章节)        ├── index.md       ← 章节首页(可选)        └── config.md      ← 子章节

知识库根目录不要放 index.md。打开 /docs/my-tutorial/ 看到的是第一篇文档,或者 _meta.md 里 homepage 指定的那篇,见下方指定首页文章。

_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 随机图)
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)

章节目录要写进 _meta.md 的 dirs,没写进去的目录,里面的文档不会出现在侧边栏。子目录里的 index.md 是这个章节的首页,它的 title 也是侧边栏里的章节名。默认情况下,章节首页会自动列出这一章的文档卡片,index.md 的正文不显示;这一章还没有文档时,才显示正文。

如果你希望章节首页展示自己写的内容,在这个 index.md 里关闭 autoRender:

---
title: 进阶配置
autoRender: false
---

## 这一章讲什么

这里是自定义的章节介绍,不会自动列出文档卡片。

关闭后,读者通过侧边栏进入这一章的各篇文档。

使用建议

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