Sveltepress

介绍

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

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

自动生成侧边栏

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

import { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct


UserConfig


object, or a function that returns it.
The function receives a


ConfigEnv


object.
defineConfig } from 'vite'

export default function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct


UserConfig


object, or a function that returns it.
The function receives a


ConfigEnv


object.
defineConfig({
  UserConfig.plugins?: PluginOption[] | undefined
Array of vite plugins to use.
plugins: [
    function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
      SveltepressVitePluginOptions.theme?: ResolvedTheme | undefinedtheme: function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme({
        DefaultThemeOptions.sidebar?: Record<string, LinkItem[]> | AutoSidebarOptions | undefinedsidebar: {
          AutoSidebarOptions.enabled: boolean
Enable auto-generated sidebar
enabled: true,
        },
      }),
    }),
  ],
})
ts

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

自动侧边栏跳过历史版本

历史版本快照目录（如 /v/1.0/，以及 /zh/v/1.0/ 这类按语言组合的路径）会被跳过，即使 roots 显式包含 /v/ 也一样。冻结历史版本仍使用快照元数据中的侧边栏。

选项

选项类型默认值说明
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 { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct


UserConfig


object, or a function that returns it.
The function receives a


ConfigEnv


object.
defineConfig } from 'vite'

export default function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct


UserConfig


object, or a function that returns it.
The function receives a


ConfigEnv


object.
defineConfig({
  UserConfig.plugins?: PluginOption[] | undefined
Array of vite plugins to use.
plugins: [
    function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
      SveltepressVitePluginOptions.theme?: ResolvedTheme | undefinedtheme: function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme({
        DefaultThemeOptions.sidebar?: Record<string, LinkItem[]> | AutoSidebarOptions | undefinedsidebar: {
          '/foo/': [
            {
              WithTitle.title?: string | undefinedtitle: 'Bar',
              LinkItem.to?: string | undefinedto: '/foo/bar/',
            },
            {
              WithTitle.title?: string | undefinedtitle: 'Zoo',
              LinkItem.collapsible?: boolean | undefinedcollapsible: true,
              LinkItem.items?: LinkItem[] | undefineditems: [
                {
                  WithTitle.title?: string | undefinedtitle: 'Sub item',
                  LinkItem.to?: string | undefinedto: '/sub/item/link',
                },
              ],
            },
            {
              WithTitle.title?: string | undefinedtitle: 'External github page',
              LinkItem.to?: string | undefinedto: 'https://github.com',
            },
          ],
        },
      }),
    }),
  ],
})
ts
Expand code

title

侧边栏项的标题

to

链接地址

自动识别外部链接

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

collapsible

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

items

子项

嵌套子项

支持嵌套子项