預設主題設定

主題設定讓您可以自訂您的主題。您可以在設定檔中透過 themeConfig 選項定義主題設定

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

  // Theme related configurations.
  themeConfig: {
    logo: '/logo.svg',
    nav: [...],
    sidebar: { ... }
  }
}

本頁面中說明的選項僅適用於預設主題。不同的主題需要不同的主題設定。使用自訂主題時，主題設定物件會傳遞給主題，讓主題可以根據設定定義條件式行為。

i18nRouting

類型：布林值

將語言環境變更為 zh 會將網址從 /foo（或 /en/foo/）變更為 /zh/foo。您可以透過將 themeConfig.i18nRouting 設為 false 來停用此行為。

logo

類型：可設定主題的圖片

在導覽列中顯示的標誌檔案，位於網站標題正前方。接受路徑字串或物件，以設定淺色/深色模式的不同標誌。

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

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

siteTitle

類型：字串 | false

您可以自訂此項目，以取代導覽列中的預設網站標題（應用程式設定中的 title）。設為 false 時，導覽列中的標題會停用。當您有已包含網站標題文字的 logo 時，這會很有用。

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

nav

類型：導覽列項目

導覽列選單項目的設定。更多詳細資訊請參閱預設主題：導覽列。

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
}

類型：側邊欄

側邊欄選單項目的設定。更多詳細資訊請參閱預設主題：側邊欄。

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 = {
  /**
   * The text label of the item.
   */
  text?: string

  /**
   * The link of the item.
   */
  link?: string

  /**
   * The children of the item.
   */
  items?: SidebarItem[]

  /**
   * If not specified, group is not collapsible.
   *
   * If `true`, group is collapsible and collapsed by default
   *
   * If `false`, group is collapsible but expanded by default
   */
  collapsed?: boolean

  /**
   * Base path for the children items.
   */
  base?: string

  /**
   * Customize text that appears on the footer of previous/next page.
   */
  docFooterText?: string

  rel?: string
  target?: string
}

aside

類型：boolean | 'left'
預設：true
可透過 frontmatter 覆寫每個頁面

將此值設定為 false 可避免渲染 aside 容器。
將此值設定為 true 可將 aside 渲染至右側。
將此值設定為 left 可將 aside 渲染至左側。

如果您想在所有視窗中停用它，您應該使用 outline: false。

outline

類型：Outline | Outline['level'] | false
層級可透過 frontmatter 覆寫每個頁面

將此值設定為 false 可避免渲染 outline 容器。請參閱此介面以取得更多詳細資訊

interface Outline {
  /**
   * The levels of headings to be displayed in the outline.
   * Single number means only headings of that level will be displayed.
   * If a tuple is passed, the first number is the minimum level and the second number is the maximum level.
   * `'deep'` is same as `[2, 6]`, which means all headings from `<h2>` to `<h6>` will be displayed.
   *
   * @default 2
   */
  level?: number | [number, number] | 'deep'

  /**
   * The title to be displayed on the outline.
   *
   * @default 'On this page'
   */
  label?: string
}

socialLinks

類型：SocialLink[]

您可以定義此選項，在導覽列中顯示您的社群帳戶連結和圖示。

export default {
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: '...' },
      // You can also add custom icons by passing SVG as string:
      {
        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: '...',
        // You can include a custom label for accessibility too (optional but recommended):
        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
可透過 frontmatter 覆寫每個頁面

頁尾設定。您可以在頁尾新增訊息或版權文字，但它只會在頁面不包含側邊欄時顯示。這是基於設計考量。

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
可透過 frontmatter 覆寫每個頁面

編輯連結讓您在 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 }
}

algolia

類型：AlgoliaSearch

使用 Algolia DocSearch 支援搜尋您的文件網站的選項。在預設主題：搜尋中了解更多資訊。

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

在此處查看完整選項。

carbonAds

類型：CarbonAdsOptions

顯示 Carbon Ads 的選項。

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

export interface CarbonAdsOptions {
  code: string
  placement: string
}

在預設主題：Carbon 廣告中深入了解

docFooter

類型：DocFooter

可用於自訂出現在前一頁和下一頁連結上方的文字。如果文件不是用英文撰寫，這會很有幫助。也可以用來停用前一頁/下一頁連結。如果你想有選擇性地啟用/停用前一頁/下一頁連結，可以使用 frontmatter。

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

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

darkModeSwitchLabel

類型：字串
預設值：外觀

可用於自訂深色模式切換標籤。此標籤只會顯示在行動裝置檢視中。

lightModeSwitchTitle

類型：字串
預設值：切換至淺色主題

可用於自訂滑鼠移到上面時顯示的淺色模式切換標題。

darkModeSwitchTitle

類型：字串
預設值：切換至深色主題

可用於自訂滑鼠移到上面時顯示的深色模式切換標題。

sidebarMenuLabel

類型：字串
預設值：選單

可用於自訂側邊欄選單標籤。此標籤只會顯示在行動裝置檢視中。

returnToTopLabel

類型：字串
預設值：返回頂端

可用於自訂返回頂端按鈕的標籤。此標籤只會顯示在行動裝置檢視中。

langMenuLabel

類型：字串
預設值：變更語言

可用於自訂導覽列中語言切換按鈕的 aria 標籤。這只會在使用 i18n 時使用。

externalLinkIcon

類型：布林值
預設值：false

是否在 markdown 中的外部連結旁邊顯示外部連結圖示。

預設主題設定 ​

i18nRouting ​

logo ​

siteTitle ​

nav ​

sidebar ​

aside ​

outline ​

socialLinks ​

footer ​

editLink ​

lastUpdated ​

algolia ​

carbonAds ​

docFooter ​

darkModeSwitchLabel ​

lightModeSwitchTitle ​

darkModeSwitchTitle ​

sidebarMenuLabel ​

returnToTopLabel ​

langMenuLabel ​

externalLinkIcon ​