默认主题配置

主题配置可以自定义主题。可以通过将 themeConfig 添加到配置文件来进行主题配置：

typescript

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

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

配置选项总览

配置项	说明	类型	默认值
`logo`	导航栏上显示的 Logo，位于站点标题前	`ThemeableImage`	-
`siteTitle`	自定义导航中的站点标题，设为 `false` 可禁用	`string \| false`	-
`nav`	导航菜单项的配置	`NavItem`	-
`sidebar`	侧边栏菜单项的配置	`Sidebar`	-
`aside`	定义 aside 容器的位置，可通过 frontmatter 覆盖	`boolean \| 'left'`	`true`
`outline`	大纲配置，可通过 frontmatter 覆盖层级	`Outline \| Outline['level'] \| false`	-
`socialLinks`	导航栏中展示的社交帐户链接	`SocialLink[]`	-
`footer`	页脚配置，可通过 frontmatter 覆盖	`Footer`	-
`editLink`	编辑链接配置，每个页面可通过 frontmatter 覆盖	`EditLink`	-
`lastUpdated`	上次更新的文本和日期格式配置	`LastUpdatedOptions`	-
`algolia`	Algolia DocSearch 搜索配置	`AlgoliaSearch`	-
`carbonAds`	Carbon Ads 配置	`CarbonAdsOptions`	-
`docFooter`	自定义上一页和下一页链接上方的文本	`DocFooter`	-
`darkModeSwitchLabel`	深色模式开关标签（仅移动端显示）	`string`	`Appearance`
`lightModeSwitchTitle`	浅色模式开关标题（悬停时显示）	`string`	`Switch to light theme`
`darkModeSwitchTitle`	深色模式开关标题（悬停时显示）	`string`	`Switch to dark theme`
`sidebarMenuLabel`	侧边栏菜单标签（仅移动端显示）	`string`	`Menu`
`returnToTopLabel`	返回顶部按钮的标签（仅移动端显示）	`string`	`Return to top`
`langMenuLabel`	语言切换按钮的 aria-label（仅使用 i18n 时）	`string`	`Change language`
`externalLinkIcon`	是否在 markdown 中的外部链接旁显示外部链接图标	`boolean`	`false`

详细配置说明

logo

导航栏上显示的 Logo，位于站点标题前。可以接受一个路径字符串，或者一个对象来设置在浅色/深色模式下不同的 Logo。

typescript

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

类型定义：

typescript

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

siteTitle

可以自定义此项以替换导航中的默认站点标题（应用配置中的 title）。当设置为 false 时，导航中的标题将被禁用。这在当 logo 已经包含站点标题文本时很有用。

typescript

export default {
  themeConfig: {
    siteTitle: "Hello World"
  }
}

nav

导航菜单项的配置

typescript

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" }
        ]
      }
    ]
  }
}

类型定义：

typescript

type NavItem = NavItemWithLink | NavItemWithChildren

interface NavItemWithLink {
  text: string
  link: string | ((payload: PageData) => string)
  activeMatch?: string
  target?: string
  rel?: string
  noIcon?: boolean
}

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

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

侧边栏菜单项的配置

typescript

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

类型定义：

typescript

export type Sidebar = SidebarItem[] | SidebarMulti

export interface SidebarMulti {
  [path: string]: SidebarItem[]
}

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

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

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

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

aside

将此值设置为 false 可禁用 aside 容器
将此值设置为 true 将在页面右侧渲染
将此值设置为 left 将在页面左侧渲染

如果想对所有页面禁用它，应该使用 outline: false。每个页面可以通过 frontmatter 覆盖

outline

将此值设置为 false 可禁止渲染大纲容器。每个页面可以通过 frontmatter 覆盖层级

类型定义：

typescript

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

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

socialLinks

可以定义此选项以在导航栏中展示带有图标的社交帐户链接。

typescript

export default {
  themeConfig: {
    socialLinks: [
      { icon: "github", link: "https://github.com/vuejs/vitepress" },
      { icon: "twitter", link: "..." },
      // 可以通过将 SVG 作为字符串传递来添加自定义图标：
      {
        icon: {
          svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
        },
        link: "...",
        // 也可以为无障碍添加一个自定义标签 (可选但推荐):
        ariaLabel: "cool link"
      }
    ]
  }
}

类型定义：

typescript

interface SocialLink {
  icon: string | { svg: string }
  link: string
  ariaLabel?: string
}

页脚配置。可以添加 message 和 copyright。由于设计原因，仅当页面不包含侧边栏时才会显示页脚。可以通过 frontmatter 进行覆盖

typescript

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

类型定义：

typescript

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

editLink

编辑链接可让显示链接以编辑 Git 管理服务（例如 GitHub 或 GitLab）上的页面。有关详细信息，请参阅默认主题：编辑链接。每个页面可以通过 frontmatter 覆盖。

typescript

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

类型定义：

typescript

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

lastUpdated

允许自定义上次更新的文本和日期格式。

typescript

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

类型定义：

typescript

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

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

algolia

支持使用 Algolia DocSearch 搜索站点文档。在默认主题：搜索中了解更多信息。

类型定义：

typescript

export interface AlgoliaSearchOptions extends DocSearchProps {
  locales?: Record<string, Partial<DocSearchProps>>
}

carbonAds

一个配置即可展示 Carbon Ads。

typescript

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

类型定义：

typescript

export interface CarbonAdsOptions {
  code: string
  placement: string
}

docFooter

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

typescript

export default {
  themeConfig: {
    docFooter: {
      prev: "Pagina prior",
      next: "Proxima pagina"
    }
  }
}

类型定义：

typescript

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

其他标签配置

以下配置项用于自定义各种 UI 元素的标签文本：

darkModeSwitchLabel：深色模式开关标签（仅移动端显示），默认值：Appearance
lightModeSwitchTitle：浅色模式开关标题（悬停时显示），默认值：Switch to light theme
darkModeSwitchTitle：深色模式开关标题（悬停时显示），默认值：Switch to dark theme
sidebarMenuLabel：侧边栏菜单标签（仅移动端显示），默认值：Menu
returnToTopLabel：返回顶部按钮的标签（仅移动端显示），默认值：Return to top
langMenuLabel：语言切换按钮的 aria-label（仅使用 i18n 时），默认值：Change language

externalLinkIcon

是否在 markdown 中的外部链接旁显示外部链接图标

typescript

export default {
  themeConfig: {
    externalLinkIcon: true
  }
}