Zudoku导航与站点配置详解:让API文档结构一目了然
Zudoku导航与站点配置详解:让API文档结构一目了然
Zudoku 是一款用于构建高质量交互式 API 文档的开源框架。而决定文档"好不好找"的关键,正是 Zudoku 导航配置(navigation)与 站点配置(site)。本文将带你快速掌握这两大核心能力:如何用一个 navigation 数组同时控制顶部标签页和左侧侧边栏,如何用 navigationRules 微调插件自动生成的目录,以及如何通过 site 配置打造专属品牌外观。无需大量代码,看完即可上手 🚀
为什么导航结构决定文档体验
想象一下:你的 API 文档有 50 个页面,但没有清晰的分组、图标和层级——读者会立刻迷失。Zudoku 的设计理念是"一份配置,两处生效":
navigation数组的根级条目 → 显示为顶部的标签页(Tabs)- 嵌套的
items→ 构建成左侧的侧边栏树
也就是说,你只需要维护一份导航数据,页面顶部和侧边栏就会自动保持一致。官方文档站的真实配置就在 zudoku.config.tsx,导航部分从 第75行 开始,可以直接参考。
快速上手:导航配置基本结构
在 zudoku.config.tsx 中找到 navigation 字段,最简形态如下:
{
navigation: [
{
type: "category", // 分组(折叠面板)
label: "Documentation",
icon: "book",
items: [
"documentation/introduction", // 字符串简写 = 一篇 Markdown 文档
"documentation/quickstart",
],
},
{ type: "link", to: "/api", label: "API Reference", icon: "code" },
],
}
两个小窍门:
- 字符串简写:
"guides/quickstart"等价于{ type: "doc", file: "guides/quickstart" },不写label时会自动取文档 frontmatter 的title,配置更简洁; - 图标:
icon直接填 Lucide 图标 名称,如book、code、file-text,侧边栏立刻变得直观。
完整配置项说明见官方 Navigation 文档。
7 种导航项类型全解
Zudoku 支持 7 种导航项,覆盖几乎所有目录组织场景:
| 类型 | 作用 | 典型用途 |
|---|---|---|
category |
可折叠的分组 | 按主题划分目录树 |
doc |
引用一篇 Markdown 文档 | 普通页面 |
link |
直达路径或外部 URL | API Reference、状态页 |
custom-page |
React 组件页面 | 落地页、仪表盘 |
separator |
水平分隔线 | 视觉分组 |
section |
不可点击的分组小标题 | "Getting Started" 这类标签 |
filter |
侧边栏内联搜索框 | 快速筛选文档 |
几个高频进阶特性 📌:
display显示控制:"auth"(仅登录可见)、"anon"(仅访客可见)、"hide"(彻底隐藏),还可以传入回调函数按角色自定义;badge徽章:给条目加上Beta、v2.0之类的彩色标签;category.link:让分组标题本身也可点击,既能当分组又能当"落地页";sidebar_label:在 Markdown frontmatter 中写sidebar_label,可让侧边栏显示短标题,而不改动文档原标题。
落地页 + 隐藏标签的经典组合
想让首页是一个完全不依赖默认布局的落地页?用 custom-page + display: "hide" + layout: "none" 即可,示例如下(同样可在官方配置文件中找到):
navigation: [
{
type: "custom-page",
path: "/",
display: "hide",
layout: "none",
element: <LandingPage />,
},
// …其他分类
]
分层导航(Stack):给大目录瘦身
当某个分组内容特别多(比如几十个 API 端点)时,全部平铺在侧边栏会非常拥挤。把 stack: true 加到 category 或 link 上,点击后它会以整屏面板的形式滑入展示子项,并自带"返回"按钮:
{
type: "category",
label: "Cargo Handbook",
stack: true, // 点击后以独立面板打开
items: ["cargo-handbook/hazardous", "cargo-handbook/living"],
}
仓库中的 cosmo-cargo 示例 就大量使用了这种"分层 + 折叠"组合,是一个很好的参考项目。
下面的横幅图来自该示例项目的文档站(documentation.mdx 引用了它),可以看到真实项目中"品牌页头 + 结构化导航"的实际效果:
用 navigationRules 微调自动生成的侧边栏
当你接入 OpenAPI / GraphQL 插件后,侧边栏目录是自动生成的。想插入一篇"Getting Started"、改个图标、调个顺序?navigationRules 让你不动源文件就能精确修改:
| 规则类型 | 作用 |
|---|---|
insert |
在匹配项之前/之后插入条目 |
modify |
修改 label、icon、badge、折叠状态等 |
remove |
移除某个条目 |
sort |
用自定义比较器排序 |
move |
把条目挪到别的位置 |
match 使用"斜杠分段"定位,第一段是顶部标签名,后面逐级深入(支持 -1 表示最后一项、索引号表示第 N 项):
navigationRules: [
{
type: "insert",
match: "Shipments/0", // Shipments 标签下的第 1 个条目
position: "before",
items: [
{ type: "doc", file: "api-shipments/getting-started", icon: "plane-takeoff" },
],
},
]
执行后,侧边栏第一项前就插入了"Getting Started"文档,效果如下:
想在侧边栏末尾追加一个外部链接(比如系统状态页),只需把 match 写成 Shipments/-1、position 设为 "after":
modify 规则则可以原地更换图标或折叠状态,例如给某个分组换上 box 图标:
完整规则语法(含排序、移动、规则执行顺序)请看 Navigation Rules 指南。
站点级配置:用 site 打造品牌外观
site 字段控制整个站点的"门面",在 zudoku.config.tsx 中一目了然:
site.title:logo 旁边的站点标题;site.logo:支持light/dark双主题 logo,建议同时设置width/height防止布局抖动;site.banner:页面顶部的公告条,可设颜色(info、caution、danger等)并允许关闭;site.sidebar:侧边栏默认可折叠,可配置折叠按钮的位置(top/center/bottom)和显示时机(always/hover);site.notFoundPage:自定义 404 页面组件。
{
site: {
title: "My API Documentation",
logo: { src: { light: "/logo-light.svg", dark: "/logo-dark.svg" }, alt: "Logo" },
banner: { message: "Welcome to our beta documentation!", color: "info", dismissible: true },
sidebar: { collapsible: true, togglePosition: "bottom" },
},
}
底部页脚由 site.footer 独立配置,支持多列链接、版权信息和社交图标,详见 Footer 配置文档。品牌与布局的完整选项在 Branding & Layout 中有详细说明。
大型文档站的最佳实践:拆分配置文件
配置项太多时,zudoku.config.tsx 会变得又长又乱。由于配置文件就是普通的 TS 文件,可以把导航拆成独立模块再导入——官方文档站就是这么做的:
- 导航数据集中在 sidebar.ts,用
category+icon组织出 "Configuration / Writing / OpenAPI / Authentication" 等清晰分组,甚至给blog条目加上了Beta徽章; - 主配置文件 zudoku.config.tsx 只需
import { components, docs } from "./sidebar"一行引用。
这种"导航即代码、单独维护"的模式,让文档结构随项目规模增长依然保持整洁。
核心资料导航
| 资源 | 路径 |
|---|---|
| 导航配置官方文档 | navigation.mdx |
| 站点品牌与布局配置 | site.md |
| 配置文件总览 | overview.md |
| 页脚配置 | footer.mdx |
| Navigation Rules 指南(含配图) | navigation-rules.mdx |
| 官方文档站真实配置 | zudoku.config.tsx |
| 导航拆分示例 | sidebar.ts |
| 分层导航实战示例 | examples/cosmo-cargo/ |
小结
一句话回顾:navigation 定义结构,navigationRules 修正细节,site 决定外观。掌握这三块配置,你的 Zudoku 文档站就能做到目录层级清晰、品牌感拉满、读者一步到位 🎯。建议从官方文档站的 zudoku.config.tsx 抄起,改着改着就会用了。



