Zudoku导航与站点配置详解:让API文档结构一目了然

原创2026-11-14 09:25:491,221 阅读

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" },
  ],
}

两个小窍门:

  1. 字符串简写:"guides/quickstart" 等价于 { type: "doc", file: "guides/quickstart" },不写 label 时会自动取文档 frontmatter 的 title,配置更简洁;
  2. 图标: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 引用了它),可以看到真实项目中"品牌页头 + 结构化导航"的实际效果:

Zudoku 文档站顶部横幅与导航结构示例

用 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"文档,效果如下:

Zudoku navigationRules 在侧边栏开头插入 Getting Started 文档的效果

想在侧边栏末尾追加一个外部链接(比如系统状态页),只需把 match 写成 Shipments/-1、position 设为 "after":

Zudoku navigationRules 在侧边栏末尾插入 System Status 链接的效果

modify 规则则可以原地更换图标或折叠状态,例如给某个分组换上 box 图标:

Zudoku navigationRules 修改侧边栏条目图标与折叠状态的配置示例

完整规则语法(含排序、移动、规则执行顺序)请看 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 抄起,改着改着就会用了。

登录后查看全文
zudoku