Nextra _meta.ts 文档导航迁移记录

以下是正文

一、背景与目标

BDI 官网文档系统的左侧导航此前采用自定义方案：在 MDX 文件的 frontmatter 中添加 sidebarOrder 字段，由 buildSidebarTree() 函数读取并排序。该方案存在以下问题：

• 不符合 Nextra v4 官方约定：Nextra 提供了 _meta.ts 文件约定来管理导航排序、标题、隐藏、分隔符等功能
• 扩展性差：每新增一篇文档都需要手动设置 sidebarOrder 数值，维护成本高
• 缺少高级功能：无法通过配置实现导航分隔符、隐藏页面等功能

本次任务目标：按照 Nextra v4 官方指南，重新启用 _meta.ts 文件，替换自定义的 sidebarOrder 方案。

二、变更内容

2.1 新增 _meta.ts 文件

在 content/zh/docs/ 和 content/en/docs/ 目录分别创建 _meta.ts 文件：

// content/zh/docs/_meta.ts
import type { MetaRecord } from "nextra";
 
const meta: MetaRecord = {
  index: "BDI 文档",
  "getting-started": "快速开始",
};
 
export default meta;

// content/en/docs/_meta.ts
import type { MetaRecord } from "nextra";
 
const meta: MetaRecord = {
  index: "BDI Documentation",
  "getting-started": "Getting Started",
};
 
export default meta;

关键特性：

• 对象键的顺序即为导航排序
• 值为字符串时直接作为导航标题
• 支持 display: "hidden" 隐藏页面
• 支持 type: "separator" 添加分隔符

2.2 重构 buildSidebarTree() 函数

将 app/[locale]/docs/layout.tsx 中的 buildSidebarTree() 函数从自定义排序逻辑改为基于 _meta.ts 数据：

核心改动：

• 引入 MetaJsonFile 类型，从 pageMap 中提取 _meta.ts 数据
• 按 Object.entries(metaData) 顺序构建侧边栏，确保排序与 _meta.ts 一致
• 未列入 _meta.ts 的页面自动追加到末尾
• 新增 resolveMetaTitle()、isHidden()、isSeparator() 辅助函数

2.3 更新侧边栏组件

components/docs/docs-sidebar.tsx 的变更：

• 移除 order: number 字段（不再需要）
• 新增 isSeparator?: boolean 字段
• 渲染逻辑增加分隔符支持：有标题时显示为分组标题，无标题时显示为横线

2.4 移除自定义排序代码

• app/[locale]/docs/[[...mdxPath]]/page.tsx 中的 prev/next 导航排序已改为直接使用 pageMap 自然顺序
• 所有 MDX 文件的 frontmatter 中移除了 sidebarOrder 字段

2.5 新增演示文档内容

为充分演示 _meta.ts 的各项能力，新增了丰富的文档内容：

新增文件夹（折叠支持）：

• content/zh/docs/platform/ — 管理平台（含 index、sales、procurement、inventory）
• content/zh/docs/capability/ — 业务能力（含 index、team、goal）

新增页面：

• solution-overview.mdx — 解决方案概述
• faq.mdx — 常见问题
• internal-notes.mdx — 内部笔记（隐藏页面演示）

新增子文件夹 _meta.ts：

• content/zh/docs/platform/_meta.ts
• content/zh/docs/capability/_meta.ts
• content/en/docs/platform/_meta.ts

清理：

• 删除空占位文件夹 first/ 和 second/

2.6 受影响文件清单

三、Nextra _meta.ts 功能速查

排序

键的顺序即为侧边栏排序：

export default {
  index: "首页", // 第1项
  guide: "使用指南", // 第2项
  api: "API 文档", // 第3项
};

隐藏

export default {
  internal: { display: "hidden" }, // 不显示在侧边栏，但 URL 仍可访问
};

分隔符

export default {
  index: "首页",
  "---": { type: "separator", title: "高级" },
  advanced: "高级功能",
};

文件夹标题

export default {
  "my-folder": "自定义文件夹名称",
};

四、验证结果

• pnpm check:unsafe 通过（0 问题）
• pnpm check 通过（0 修复）
• pnpm build 成功（43 个静态页面生成，含 19+ 个文档页面）
• pnpm dev 运行正常
• 中文文档导航完整展示：排序 → 分隔符 → 文件夹（折叠） → 隐藏页面
• 英文文档导航同步正常
• 隐藏页面 /docs/internal-notes 通过 URL 可访问但不出现在侧边栏
• 嵌套文件夹 /docs/platform/* 和 /docs/capability/* 正确折叠展开
• 分隔符正确渲染为分组标题和分隔线

五、_meta.ts 能力演示总览

本次实现完整演示了 Nextra v4 _meta.ts 文件约定的以下核心能力：

六、博客系统 _meta.ts 与精选侧边栏

6.1 博客 _meta.ts

博客系统的 _meta.ts 保持为空，让 Nextra 自动发现所有 MDX 文件。新增或删除博客文章无需维护 _meta.ts：

// content/zh/blog/_meta.ts
import type { MetaRecord } from "nextra";
 
// 保持为空，让 Nextra 自动发现所有文章
const meta: MetaRecord = {};
 
export default meta;

6.2 精选文章功能

精选文章通过 MDX frontmatter 中的 featured 字段管理。支持整数和分级格式（如 1、2、2-1、2-2），数字越小排序越靠前，同级按文章标题排序。博客管理员只需在单篇文章的 frontmatter 中添加或移除 featured 字段即可控制精选：

---
title: "文章标题"
category: "分类"
featured: 2-1
---

• featured: 1 排在第一位，featured: 2 排在第二位
• 支持分级排序：2-1 排在 2 之后、2-2 之前
• 同级（如两个 2-1）按文章标题进行 locale 排序
• 没有 featured 字段的文章不会出现在精选列表中
• 删除文章时无需额外清理，精选列表自动更新
• 点击任何筛选器（精选或分类）页面自动滚动到顶部

6.3 BlogSidebar 组件

新建 components/blog/blog-sidebar.tsx 客户端组件，将精选文章列表与分类筛选合并到博客左侧导航：

精选推荐采用过滤模式（非导航模式），点击精选文章会通过 URL 查询参数 ?featured=slug 过滤博客列表，再次点击可取消过滤。

6.4 博客变更清单

七、总结

本次迁移将文档导航和博客导航统一切换到 Nextra v4 官方的 _meta.ts 文件约定。

文档系统：

1. 符合官方规范：使用 Nextra 内置的 MetaJsonFile 和 MetaRecord 类型
2. 功能更丰富：支持排序、隐藏、分隔符等多种导航配置
3. 维护更简单：集中在 _meta.ts 文件管理，无需修改每个 MDX 文件
4. 扩展性更好：新增文档只需在 _meta.ts 中添加一行配置

博客系统：

1. 精选侧边栏：通过 frontmatter featured 管理精选文章，支持分级排序（如 1、2-1、2-2），同级按标题排序
2. 零维护：博客无 _meta.ts，新增/删除 MDX 文件无需额外维护
3. 删除安全：删除文章后精选列表自动更新，不影响页面渲染
4. 草稿支持：frontmatter 中 draft: true 即可隐藏文章，实现草稿和撤销发布功能
5. 滚动复位：点击任何筛选器（精选或分类）页面自动滚动到顶部
6. 优雅设计：分类颜色标签、Star 图标、分隔线分区，视觉层次清晰

• 版本: 1.5.0
• 时间: 2026-02-22 23:30:00
• 作者: Claude Opus 4.6
• 简介: 精选支持分级排序，筛选器点击自动滚动到顶部