默认主题配置

主题配置让你可以自定义你的主题。你可以通过配置文件中的 themeConfig 选项定义主题配置：

export default {
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',

  // 主题相关配置
  themeConfig: {
    logo: '/logo.svg',
    nav: [...],
    sidebar: { ... }
  }
}

本页面记录了 VitePress 默认主题的所有可配置选项。如果你使用自定义主题，这些选项可能不会生效，或者可能表现不同。

站点标题和 Logo

siteTitle

类型： string | false
默认值： config.title
详细信息：
你可以自定义此项来替换导航中的默认站点标题（来自 config.title）。当设置为 false 时，导航中的标题将被禁用。这在你有 logo 已经包含站点标题文本时很有用。

export default {
  themeConfig: {
    siteTitle: 'My Custom Title'
  }
}

logo

类型： ThemeableImage
详细信息：
Logo 文件显示在导航栏中，就在站点标题之前。接受路径字符串，或者一个对象来为浅色/深色模式设置不同的 Logo。

export default {
  themeConfig: {
    logo: '/logo.svg'
  }
}

type ThemeableImage =
  | string
  | { src: string; alt?: string }
  | { light: string; dark: string; alt?: string }

export default {
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide' },
      {
        text: 'Dropdown Menu',
        items: [
          { text: 'Item A', link: '/item-1' },
          { text: 'Item B', link: '/item-2' },
          { text: 'Item C', link: '/item-3' }
        ]
      }
    ]
  }
}

type NavItem = NavItemWithLink | NavItemWithChildren

interface NavItemWithLink {
  text: string
  link: string
  activeMatch?: string
  target?: string
  rel?: string
  noIcon?: boolean
}

interface NavItemChildren {
  text?: string
  items: NavItemWithLink[]
}

interface NavItemWithChildren {
  text?: string
  items: (NavItemChildren | NavItemWithLink)[]
  activeMatch?: string
}

类型： Sidebar
详细信息：
侧边栏菜单项的配置。你可以在默认主题：侧边栏了解更多详细信息。

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
          ...
        ]
      }
    ]
  }
}

export type Sidebar = SidebarItem[] | SidebarMulti

export interface SidebarMulti {
  [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string }
}

export type SidebarItem = {
  /**
   * 侧边栏项的文本标签
   */
  text?: string

  /**
   * 侧边栏项的链接
   */
  link?: string

  /**
   * 侧边栏项的子项
   */
  items?: SidebarItem[]

  /**
   * 如果未指定，组不可折叠。
   *
   * 如果为 `true`，组可折叠并且默认折叠。
   *
   * 如果为 `false`，组可折叠但默认展开。
   */
  collapsed?: boolean

  /**
   * 侧边栏项的基础路径
   */
  base?: string

  /**
   * 自定义侧边栏项的文档页脚文本
   */
  docFooterText?: string

  /**
   * 侧边栏项的相对路径
   */
  rel?: string

  /**
   * 侧边栏项的目标
   */
  target?: string
}

aside

类型： boolean | 'left'
默认值： true
详细信息：
如果设置为 false，则不会渲染 aside 容器。如果设置为 true，则 aside 渲染到右侧。如果设置为 'left'，则 aside 渲染到左侧。

export default {
  themeConfig: {
    aside: false
  }
}

outline

类型： Outline | Outline['level'] | false
默认值： 2
详细信息：
配置在 outline 中显示的标题级别。你可以通过传递一个数字来指定特定级别，或者你可以通过传递包含 level 和 label 的对象来提供自定义级别和标签。设置为 false 以隐藏 outline。

export default {
  themeConfig: {
    outline: {
      level: 'deep', // 右侧的侧边栏将显示从 h2 到 h6 的标题
      label: 'On this page' // 自定义右侧侧边栏的标题
    }
  }
}

interface Outline {
  /**
   * 要在 outline 中显示的标题级别。
   * 单个数字表示只显示该级别的标题。
   * 如果传递的是一个元组，第一个数字是最小级别，第二个数字是最大级别。
   * `'deep'` 与 `[2, 6]` 相同，将显示从 `<h2>` 到 `<h6>` 的所有标题。
   *
   * @default 2
   */
  level?: number | [number, number] | 'deep'

  /**
   * 显示在 outline 上的标题。
   *
   * @default 'On this page'
   */
  label?: string
}

社交链接

socialLinks

类型： SocialLink[]
详细信息：
你可以定义此选项以在导航中显示带有图标的社交帐户链接。

export default {
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: '...' },
      // 你也可以为链接添加自定义图标：
      {
        icon: {
          svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...Z"/></svg>'
        },
        link: '...',
        // 你也可以包含一个自定义标签以便无障碍访问（可选但推荐）：
        ariaLabel: 'cool link'
      }
    ]
  }
}

interface SocialLink {
  icon: SocialLinkIcon
  link: string
  ariaLabel?: string
}

type SocialLinkIcon =
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'mastodon'
  | 'npm'
  | 'slack'
  | 'twitter'
  | 'x'
  | 'youtube'
  | { svg: string }

页脚

类型： Footer
详细信息：
页脚配置。你可以添加 message 或 copyright。由于设计原因，仅当页面不包含侧边栏时才会显示页脚。

export default {
  themeConfig: {
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2019-present Evan You'
    }
  }
}

export interface Footer {
  message?: string
  copyright?: string
}

编辑链接

editLink

类型： EditLink
详细信息：
编辑链接让你显示链接以编辑 Git 管理服务（如 GitHub 或 GitLab）上的页面。有关更多详细信息，请参阅默认主题：编辑链接。

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

export interface EditLink {
  pattern: string
  text?: string
}

lastUpdated

类型： LastUpdatedOptions
详细信息：
允许自定义最后更新的文本和日期格式。

export default {
  themeConfig: {
    lastUpdated: {
      text: 'Updated at',
      formatOptions: {
        dateStyle: 'full',
        timeStyle: 'medium'
      }
    }
  }
}

export interface LastUpdatedOptions {
  /**
   * @default 'Last updated'
   */
  text?: string

  /**
   * @default
   * { dateStyle: 'short', timeStyle: 'short' }
   */
  formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
}

搜索

search

类型： AlgoliaSearch | LocalSearch | false
详细信息：
搜索配置。你可以使用 Algolia DocSearch 或基于 minisearch 的本地搜索：

export default {
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
}

有关更多详细信息，请参阅默认主题：搜索。

Carbon Ads

carbonAds

类型： CarbonAdsOptions
详细信息：
显示 Carbon Ads 的选项。

export default {
  themeConfig: {
    carbonAds: {
      code: 'your-carbon-code',
      placement: 'your-carbon-placement'
    }
  }
}

有关更多详细信息，请参阅默认主题：Carbon Ads。

export interface CarbonAdsOptions {
  code: string
  placement: string
}

文档页脚

docFooter

类型： DocFooter
详细信息：
可用于自定义出现在上一页和下一页链接上方的文本。如果不是用英语编写文档，这很有帮助。也可用于全局禁用上一页/下一页链接。如果你想有选择地启用/禁用上一页/下一页链接，可以使用 frontmatter。

export default {
  themeConfig: {
    docFooter: {
      prev: 'Previous page',
      next: 'Next page'
    }
  }
}

export interface DocFooter {
  prev?: string | false
  next?: string | false
}

自定义容器

darkModeSwitchLabel

类型： string
默认值： Appearance
详细信息：
可用于自定义深色模式开关标签。此标签仅在移动端视图中显示。

lightModeSwitchTitle

类型： string
默认值： Switch to light theme
详细信息：
可用于自定义悬停时显示的浅色模式开关标题。

darkModeSwitchTitle

类型： string
默认值： Switch to dark theme
详细信息：
可用于自定义悬停时显示的深色模式开关标题。

sidebarMenuLabel

类型： string
默认值： Menu
详细信息：
可用于自定义侧边栏菜单标签。此标签仅在移动端视图中显示。

returnToTopLabel

类型： string
默认值： Return to top
详细信息：
可用于自定义返回顶部按钮的标签。此标签仅在移动端视图中显示。

langMenuLabel

类型： string
默认值： Change language
详细信息：
可用于自定义导航栏中语言切换按钮的 aria-label。这仅在你使用 i18n 时使用。

externalLinkIcon

类型： boolean
默认值： false
详细信息：
是否在 markdown 中的外部链接旁边显示外部链接图标。

默认主题配置 ​

站点标题和 Logo ​

siteTitle ​

logo ​

导航 ​

nav ​

sidebar ​

aside ​

outline ​

社交链接 ​

socialLinks ​

页脚 ​

footer ​

编辑链接 ​

editLink ​

lastUpdated ​

搜索 ​

search ​

Carbon Ads ​

carbonAds ​

文档页脚 ​

docFooter ​

自定义容器 ​

darkModeSwitchLabel ​

lightModeSwitchTitle ​

darkModeSwitchTitle ​

sidebarMenuLabel ​

returnToTopLabel ​

langMenuLabel ​

externalLinkIcon ​

默认主题配置

站点标题和 Logo

siteTitle

logo

导航

nav

sidebar

aside

outline

社交链接

socialLinks

页脚

footer

编辑链接

editLink

lastUpdated

搜索

search

Carbon Ads

carbonAds

文档页脚

docFooter

自定义容器

darkModeSwitchLabel

lightModeSwitchTitle

darkModeSwitchTitle

sidebarMenuLabel

returnToTopLabel

langMenuLabel

externalLinkIcon