自动导航生成

Rspress 最强大的功能之一是能够从您的文件结构和 frontmatter 元数据自动生成导航栏和侧边栏。这减少了手动配置,并使您的导航与内容保持同步。

理解自动生成

工作原理

Rspress 扫描您的文档目录并:

读取文件结构(目录和文件)
解析每个文件的 frontmatter 元数据
根据约定和配置生成导航
随着内容更改动态更新导航

优势

减少配置: 更少的手动配置需要维护
始终同步: 导航随内容更改而更新
一致结构: 强制执行组织模式
更快开发: 专注于内容,而不是配置

Frontmatter 元数据

基本 Frontmatter

在任何 Markdown 文件顶部添加元数据:

---
title: 快速开始指南
description: 学习如何开始使用 Rspress
---

# 快速开始指南

您的内容在这里...

导航特定字段

控制页面在导航中的显示方式:

---
title: 高级配置
sidebar_position: 3
sidebar_label: 高级配置
---

# 高级配置

内容...

完整 Frontmatter 参考

---
# 页面元数据
title: 页面标题                    # 用于导航和页面标题
description: 页面描述              # 用于 SEO

# 导航控制
sidebar_position: 2               # 在侧边栏中的顺序(越小越靠前)
sidebar_label: 自定义标签         # 覆盖侧边栏中的标题
nav_exclude: false                # 从导航中隐藏

# 分组
group: 快速开始                   # 此页面所属的组
group_order: 1                    # 组内顺序

# 高级
slug: /custom-url                 # 自定义 URL 路径
---

侧边栏自动生成

启用自动生成

启用自动侧边栏生成:

// rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': 'auto',  // 为 /guide/ 部分自动生成
    },
  },
});

基于文件的结构

启用自动生成后,您的文件结构就成为您的侧边栏:

docs/guide/
├── index.md              # 快速开始 (sidebar_position: 1)
├── installation.md       # 安装 (sidebar_position: 2)
├── configuration.md      # 配置 (sidebar_position: 3)
└── deployment.md         # 部署 (sidebar_position: 4)

每个文件都使用其 frontmatter 中的 title 或第一个标题出现在侧边栏中。

自定义排序

使用 sidebar_position 控制顺序:

<!-- docs/guide/deployment.md -->
---
title: 部署
sidebar_position: 1    # 尽管文件顺序不同,但首先出现
---

<!-- docs/guide/index.md -->
---
title: 快速开始
sidebar_position: 2    # 第二个出现
---

结果:

指南
├── 部署          (position: 1)
└── 快速开始      (position: 2)

自定义标签

使用 sidebar_label 覆盖显示文本:

---
title: 高级配置选项和最佳实践
sidebar_label: 高级配置    # 侧边栏中的较短标签
---

分组自动生成

创建组

使用 _meta.json 文件定义组:

docs/guide/
├── _meta.json
├── basics/
│   ├── _meta.json
│   ├── installation.md
│   └── quick-start.md
└── advanced/
    ├── _meta.json
    ├── customization.md
    └── plugins.md

_meta.json 结构

定义组元数据:

// docs/guide/_meta.json
{
  "title": "指南",
  "collapsible": true,
  "collapsed": false,
  "items": {
    "basics": {
      "title": "快速开始",
      "order": 1
    },
    "advanced": {
      "title": "高级主题",
      "order": 2
    }
  }
}

// docs/guide/basics/_meta.json
{
  "title": "快速开始",
  "items": {
    "installation": {
      "title": "安装",
      "order": 1
    },
    "quick-start": {
      "title": "快速入门",
      "order": 2
    }
  }
}

结果

这会生成:

指南
├─ 快速开始
│  ├─ 安装
│  └─ 快速入门
└─ 高级主题
   ├─ 定制化
   └─ 插件

基于目录的分组

自动分组

Rspress 自动从目录创建组:

docs/api/
├── cli/
│   ├── dev.md
│   ├── build.md
│   └── preview.md
└── config/
    ├── basic.md
    └── advanced.md

生成:

API
├─ CLI
│  ├─ dev
│  ├─ build
│  └─ preview
└─ Config
   ├─ basic
   └─ advanced

组配置

通过 frontmatter 配置组:

<!-- docs/api/cli/dev.md -->
---
title: Dev 命令
group: CLI 命令
group_order: 1
---

导航栏自动生成

顶级目录

Rspress 可以从顶级目录生成导航栏:

// rspress.config.ts
export default defineConfig({
  themeConfig: {
    nav: 'auto',  // 从顶级目录生成
  },
});

docs/
├── guide/           # → 指南
├── api/             # → API
├── examples/        # → 示例
└── blog/           # → 博客

自定义自动生成的导航

混合自动生成和手动项:

export default defineConfig({
  themeConfig: {
    nav: [
      'auto',  // 自动生成项
      {
        text: '外部',
        link: 'https://example.com',
      },
    ],
  },
});

混合配置

结合自动和手动

使用两种方法以获得灵活性:

export default defineConfig({
  themeConfig: {
    sidebar: {
      // 为指南部分自动生成
      '/guide/': 'auto',

      // 为 API 部分手动配置
      '/api/': [
        {
          text: 'API 参考',
          items: [
            { text: 'CLI', link: '/api/cli' },
            { text: '配置', link: '/api/config' },
          ],
        },
      ],

      // 为示例自动生成
      '/examples/': 'auto',
    },
  },
});

实践示例

示例 1: 简单文档

docs/
├── index.md
├── installation.md
├── usage.md
└── faq.md

// rspress.config.ts
export default defineConfig({
  themeConfig: {
    sidebar: {
      '/': 'auto',  // 从根目录自动生成
    },
  },
});

Frontmatter:

<!-- docs/installation.md -->
---
title: 安装
sidebar_position: 1
---

<!-- docs/usage.md -->
---
title: 使用指南
sidebar_position: 2
---

<!-- docs/faq.md -->
---
title: 常见问题
sidebar_position: 3
---

示例 2: 分组文档

docs/
├── getting-started/
│   ├── _meta.json
│   ├── introduction.md
│   ├── installation.md
│   └── quick-start.md
├── guides/
│   ├── _meta.json
│   ├── basic.md
│   └── advanced.md
└── reference/
    ├── _meta.json
    ├── api.md
    └── cli.md

// docs/getting-started/_meta.json
{
  "title": "快速开始",
  "collapsible": true,
  "collapsed": false
}

// rspress.config.ts
export default defineConfig({
  themeConfig: {
    sidebar: 'auto',  // 自动生成所有内容
  },
});

高级技术

条件导航

基于条件显示/隐藏项:

---
title: Beta 功能
sidebar_position: 10
nav_exclude: true          # 初始时从导航中隐藏
---

动态排序

在文件名中使用数字前缀进行排序:

docs/guide/
├── 01-introduction.md
├── 02-installation.md
├── 03-configuration.md
└── 04-deployment.md

然后在 frontmatter 中去除数字:

---
title: 介绍        # 标题中没有数字
---

故障排除

导航未更新

清除缓存:

rm -rf node_modules/.rspress
npm run dev

检查 Frontmatter 语法:

---
title: 正确的 YAML
sidebar_position: 1
---

验证文件编码: 确保 UTF-8 编码

排序问题

使用一致的编号:

sidebar_position: 1   # 不是 1.0 或 "1"

检查重复项:

# 搜索重复位置
grep -r "sidebar_position: 1" docs/

性能考虑

大型站点优化

对于拥有 100+ 页面的站点:

使用策略性自动生成:

sidebar: {
  '/guide/': 'auto',        // 自动生成
  '/api/': manualConfig,    // 手动配置以提高性能
}

限制嵌套深度:

✅ 好: 2-3 层
docs/
└── guide/
    └── basics/
        └── intro.md

❌ 过深: 5+ 层

使用折叠组:

{
  "collapsible": true,
  "collapsed": true    // 默认不展开
}

最佳实践

Frontmatter 标准

始终包含标题:

---
title: 清晰、描述性的标题
---

使用一致的定位:

# 为将来插入留出间隙
sidebar_position: 10   # 第一项
sidebar_position: 20   # 第二项
sidebar_position: 30   # 第三项

保持标签简短:

---
title: 完整综合配置指南
sidebar_label: 配置指南    # 侧边栏较短
---

下一步

学习MDX 及 React 组件
探索国际化实现多语言导航
了解静态资源

::: tip 专业提示

从自动生成开始,根据需要添加手动配置
使用 _meta.json 处理复杂层次结构
在移动设备上测试导航
保持 frontmatter 在文件间的一致性 :::

::: info 资源

#自动导航生成

#理解自动生成

#工作原理

#优势

#Frontmatter 元数据

#基本 Frontmatter

#导航特定字段

#完整 Frontmatter 参考

#侧边栏自动生成

#启用自动生成

#基于文件的结构

#自定义排序

#自定义标签

#分组自动生成

#创建组

#_meta.json 结构

#结果

#基于目录的分组

#自动分组

#组配置

#导航栏自动生成

#顶级目录

#自定义自动生成的导航

#混合配置

#结合自动和手动

#实践示例

#示例 1: 简单文档

#示例 2: 分组文档

#高级技术

#条件导航

#动态排序

#故障排除

#导航未更新

#排序问题

#性能考虑

#大型站点优化

#最佳实践

#Frontmatter 标准

#下一步