侧边栏

介绍

将 sidebar 选项传递给默认主题来配置侧边栏。有两种方式来设置侧边栏：

  • 自动生成 — 自动扫描路由目录，根据文件结构和 frontmatter 生成侧边栏
  • 手动配置 — 在 Vite 配置中显式定义每个侧边栏项

自动生成侧边栏

将 sidebar 设置为 { enabled: true } 即可让 SveltePress 自动扫描 src/routes/ 目录来生成侧边栏。

import {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : ({
        : {
          : true,
        },
      }),
    }),
  ],
})
ts

SveltePress 会检测顶级路由目录（如 /guide/、/reference/）并自动构建侧边栏分组。

选项

选项类型默认值说明
enabledboolean—设为 true 启用自动侧边栏
routesDirstring'src/routes'自定义路由目录路径
rootsstring[]自动检测生成侧边栏的根路径，如 ['/guide/', '/reference/']。未指定时从顶级路由目录自动检测
sidebar: {
  enabled: true,
  routesDir: 'src/routes',
  roots: ['/guide/', '/reference/'],
}
txt

Frontmatter 控制

在 +page.md 文件中使用 frontmatter 来控制页面在自动生成侧边栏中的显示方式。

---
title: 快速开始
order: 1
sidebar: true
sidebarTitle: 从这里开始
collapsible: true
---
md
字段类型默认值说明
titlestring从文件名推断页面标题，同时用作侧边栏标签
sidebarTitlestring—覆盖侧边栏标签（优先级高于 title）
ordernumber100同级排序。数字越小越靠前
sidebarbooleantrue设为 false 可将此页面从侧边栏中排除
collapsibleboolean—侧边栏分组是否可折叠
文件命名

如果未提供 title 或 sidebarTitle，目录名会被自动转换为可读格式（如 getting-started → Getting Started）。

HMR 支持

在开发模式下使用自动侧边栏时，添加或删除路由文件会自动重新生成侧边栏——无需重启。

手动配置侧边栏

在 Vite 配置中手动定义侧边栏结构。这让你可以完全控制标题、链接、分组和排序。

自动 base

配置的链接会自动加上 base 前缀

绝对路径模式

需要将 paths.relative 设为 false

svelte.config.js
+
import adapter from '@sveltejs/adapter-static'

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    paths: {
      relative: false, 
    },
  },
}

export default config
js
import {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : ({
        : {
          '/foo/': [
            {
              : 'Bar',
              : '/foo/bar/',
            },
            {
              : 'Zoo',
              : true,
              : [
                {
                  : 'Sub item',
                  : '/sub/item/link',
                },
              ],
            },
            {
              : 'External github page',
              : 'https://github.com',
            },
          ],
        },
      }),
    }),
  ],
})
ts

title

侧边栏项的标题

to

链接地址

自动识别外部链接

与导航栏不同，侧边栏使用 Link 组件。 以 http(s) 开头的链接会被自动识别为外部链接。

collapsible

决定侧边栏分组是否可折叠。默认为 false

items

子项

嵌套子项

支持嵌套子项

在 Github 上编辑此页
最后更新于： 2026/03/19 07:24:06