垦荒学园

简体中文

English

简体中文

English

切换主题

自动导航生成 ​

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

理解自动生成 ​

工作原理 ​

Rspress 扫描您的文档目录并:

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

优势 ​

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

Frontmatter 元数据 ​

基本 Frontmatter ​

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

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

# 快速开始指南

您的内容在这里...

导航特定字段 ​

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

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

# 高级配置

内容...

完整 Frontmatter 参考 ​

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

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

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

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

侧边栏自动生成 ​

启用自动生成 ​

启用自动侧边栏生成:

typescript
// 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 控制顺序:

markdown
<!-- docs/guide/deployment.md -->
---
title: 部署
sidebar_position: 1    # 尽管文件顺序不同,但首先出现
---
markdown
<!-- docs/guide/index.md -->
---
title: 快速开始
sidebar_position: 2    # 第二个出现
---

结果:

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

自定义标签 ​

使用 sidebar_label 覆盖显示文本:

markdown
---
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 结构 ​

定义组元数据:

json
// docs/guide/_meta.json
{
  "title": "指南",
  "collapsible": true,
  "collapsed": false,
  "items": {
    "basics": {
      "title": "快速开始",
      "order": 1
    },
    "advanced": {
      "title": "高级主题",
      "order": 2
    }
  }
}
json
// 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 配置组:

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

导航栏自动生成 ​

顶级目录 ​

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

typescript
// rspress.config.ts
export default defineConfig({
  themeConfig: {
    nav: 'auto',  // 从顶级目录生成
  },
});
docs/
├── guide/           # → 指南
├── api/             # → API
├── examples/        # → 示例
└── blog/           # → 博客

自定义自动生成的导航 ​

混合自动生成和手动项:

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

混合配置 ​

结合自动和手动 ​

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

typescript
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
typescript
// rspress.config.ts
export default defineConfig({
  themeConfig: {
    sidebar: {
      '/': 'auto',  // 从根目录自动生成
    },
  },
});

Frontmatter:

markdown
<!-- 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
json
// docs/getting-started/_meta.json
{
  "title": "快速开始",
  "collapsible": true,
  "collapsed": false
}
typescript
// rspress.config.ts
export default defineConfig({
  themeConfig: {
    sidebar: 'auto',  // 自动生成所有内容
  },
});

高级技术 ​

条件导航 ​

基于条件显示/隐藏项:

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

动态排序 ​

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

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

然后在 frontmatter 中去除数字:

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

故障排除 ​

导航未更新 ​

  1. 清除缓存:
bash
rm -rf node_modules/.rspress
npm run dev
  1. 检查 Frontmatter 语法:
markdown
---
title: 正确的 YAML
sidebar_position: 1
---
  1. 验证文件编码: 确保 UTF-8 编码

排序问题 ​

  1. 使用一致的编号:
markdown
sidebar_position: 1   # 不是 1.0 或 "1"
  1. 检查重复项:
bash
# 搜索重复位置
grep -r "sidebar_position: 1" docs/

性能考虑 ​

大型站点优化 ​

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

  1. 使用策略性自动生成:
typescript
sidebar: {
  '/guide/': 'auto',        // 自动生成
  '/api/': manualConfig,    // 手动配置以提高性能
}
  1. 限制嵌套深度:
✅ 好: 2-3 层
docs/
└── guide/
    └── basics/
        └── intro.md

❌ 过深: 5+ 层
  1. 使用折叠组:
json
{
  "collapsible": true,
  "collapsed": true    // 默认不展开
}

最佳实践 ​

Frontmatter 标准 ​

  1. 始终包含标题:
markdown
---
title: 清晰、描述性的标题
---
  1. 使用一致的定位:
markdown
# 为将来插入留出间隙
sidebar_position: 10   # 第一项
sidebar_position: 20   # 第二项
sidebar_position: 30   # 第三项
  1. 保持标签简短:
markdown
---
title: 完整综合配置指南
sidebar_label: 配置指南    # 侧边栏较短
---

下一步 ​

专业提示

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

资源