知识库搭建
知识库(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.mdhomepage: advanced/config→ 使用advanced/config.md
指定后,该文章不会生成独立的页面链接,侧边栏中点击它会回到封面页。
章节首页(autoRender)
章节目录要写进 _meta.md 的 dirs,没写进去的目录,里面的文档不会出现在侧边栏。子目录里的 index.md 是这个章节的首页,它的 title 也是侧边栏里的章节名。默认情况下,章节首页会自动列出这一章的文档卡片,index.md 的正文不显示;这一章还没有文档时,才显示正文。
如果你希望章节首页展示自己写的内容,在这个 index.md 里关闭 autoRender:
---
title: 进阶配置
autoRender: false
---
## 这一章讲什么
这里是自定义的章节介绍,不会自动列出文档卡片。
关闭后,读者通过侧边栏进入这一章的各篇文档。
使用建议
- 一个知识库聚焦一个主题,比如”Astro 入门教程”或”摄影后期指南”
- 用
order控制章节顺序,让读者按正确的顺序阅读 - 子目录用
dirs配置中文名称,侧边栏显示更友好