網站設定

網站設定是您定義網站全域設定的地方。應用程式設定選項定義套用到每個 VitePress 網站的設定，無論它使用什麼主題。例如，網站的基礎目錄或標題。

概觀

設定解析

設定檔總是從 <root>/.vitepress/config.[ext] 解析，其中 <root> 是您的 VitePress 專案根目錄，而 [ext] 是其中一個受支援的副檔名。TypeScript 開箱即用。受支援的副檔名包括 .js、.ts、.mjs 和 .mts。

建議在設定檔中使用 ES 模組語法。設定檔應該預設匯出一個物件

export default {
  // app level config options
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',
  ...
}

動態 (非同步) 設定

如果您需要動態產生設定，您也可以預設匯出一個函式。例如

import { defineConfig } from 'vitepress'

export default async () => {
  const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

  return defineConfig({
    // app level config options
    lang: 'en-US',
    title: 'VitePress',
    description: 'Vite & Vue powered static site generator.',

    // theme level config options
    themeConfig: {
      sidebar: [
        ...posts.map((post) => ({
          text: post.name,
          link: `/posts/${post.name}`
        }))
      ]
    }
  })
}

您也可以使用頂層 await。例如

import { defineConfig } from 'vitepress'

const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

export default defineConfig({
  // app level config options
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',

  // theme level config options
  themeConfig: {
    sidebar: [
      ...posts.map((post) => ({
        text: post.name,
        link: `/posts/${post.name}`
      }))
    ]
  }
})

設定 Intellisense

使用 defineConfig 輔助程式將提供 TypeScript 支援的智慧感知功能，以供設定選項使用。假設您的 IDE 支援此功能，這應可在 JavaScript 和 TypeScript 中運作。

import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
})

已輸入的主題設定

預設情況下，defineConfig 輔助程式會從預設主題中預期主題設定類型

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // Type is `DefaultTheme.Config`
  }
})

如果您使用自訂主題，並想要對主題設定進行類型檢查，您需要改用 defineConfigWithTheme，並透過一般引數傳遞自訂主題的設定類型

import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // Type is `ThemeConfig`
  }
})

Vite、Vue 和 Markdown 設定

Vite
您可以使用 VitePress 設定中的 vite 選項來設定基礎 Vite 執行個體。無需建立一個獨立的 Vite 設定檔案。
Vue
VitePress 已包含 Vite 的官方 Vue 外掛模組 (@vitejs/plugin-vue)。您可以使用 VitePress 設定中的 vue 選項來設定其選項。
Markdown
您可以使用 VitePress 設定中的 markdown 選項來設定基礎 Markdown-It 執行個體。

網站元資料

標題

類型：字串
預設值：VitePress
可透過前置資料逐頁覆寫

網站標題。當使用預設主題時，這將顯示在導覽列中。

它也會用作所有個別頁面標題的預設字尾，除非已定義 titleTemplate。個別頁面的最終標題將是其第一個 <h1> 標頭的文字內容，加上全域 title 作為字尾。例如，使用以下設定和頁面內容

export default {
  title: 'My Awesome Site'
}

# Hello

頁面標題將會是 Hello | My Awesome Site。

titleTemplate

類型：字串 | 布林值
可透過 frontmatter 覆寫每個頁面

允許自訂每個頁面的標題後綴或整個標題。例如

export default {
  title: 'My Awesome Site',
  titleTemplate: 'Custom Suffix'
}

# Hello

頁面的標題會是 Hello | 客製化後綴。

若要完全自訂標題的呈現方式，可以在 titleTemplate 中使用 :title 符號

export default {
  titleTemplate: ':title - Custom Suffix'
}

這裡的 :title 會被替換成從頁面第一個 <h1> 標頭推論出的文字。先前範例頁面的標題會是 Hello - 客製化後綴。

可以將此選項設定為 false 以停用標題後綴。

description

類型：字串
預設值：A VitePress site
可透過 frontmatter 覆寫每個頁面

網站的說明。這會在頁面 HTML 中呈現為 <meta> 標籤。

export default {
  description: 'A VitePress site'
}

head

類型：HeadConfig[]
預設值：[]
可透過 frontmatter 附加至每個頁面

在頁面 HTML 的 <head> 標籤中呈現的其他元素。使用者新增的標籤會在關閉 head 標籤之前、VitePress 標籤之後呈現。

type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

範例：新增 favicon

export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // put favicon.ico in public directory, if base is set, use /base/favicon.ico

/* Would render:
  <link rel="icon" href="/favicon.ico">
*/

範例：新增 Google 字型

export default {
  head: [
    [
      'link',
      { rel: 'preconnect', href: 'https://fonts.googleapis.com' }
    ],
    [
      'link',
      { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
    ],
    [
      'link',
      { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }
    ]
  ]
}

/* Would render:
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
*/

範例：註冊服務工作人員

export default {
  head: [
    [
      'script',
      { id: 'register-sw' },
      `;(() => {
        if ('serviceWorker' in navigator) {
          navigator.serviceWorker.register('/sw.js')
        }
      })()`
    ]
  ]
}

/* Would render:
  <script id="register-sw">
    ;(() => {
      if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/sw.js')
      }
    })()
  </script>
*/

範例：使用 Google Analytics

export default {
  head: [
    [
      'script',
      { async: '', src: 'https://127.0.0.1/gtag/js?id=TAG_ID' }
    ],
    [
      'script',
      {},
      `window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'TAG_ID');`
    ]
  ]
}

/* Would render:
  <script async src="https://127.0.0.1/gtag/js?id=TAG_ID"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'TAG_ID');
  </script>
*/

lang

類型：字串
預設值：en-US

網站的 lang 屬性。這會在頁面 HTML 中呈現為 <html lang="en-US"> 標籤。

export default {
  lang: 'en-US'
}

base

類型：字串
預設值：/

網站將部署到的基本 URL。如果你計畫將網站部署在子路徑下，例如 GitHub 頁面，則需要設定此值。如果你計畫將網站部署到 https://foo.github.io/bar/，則應將 base 設定為 '/bar/'。它應該始終以斜線開頭和結尾。

base 會自動加到其他選項中所有以 / 開頭的 URL 前面，因此你只需要指定一次。

export default {
  base: '/base/'
}

路由

cleanUrls

類型：boolean
預設值：false

設定為 true 時，VitePress 會從 URL 中移除尾端的 .html。另請參閱產生乾淨的 URL。

需要伺服器支援

啟用此功能可能需要在您的託管平台上進行額外的設定。為了讓它正常運作，您的伺服器必須能夠在訪問 /foo 時提供 /foo.html 而不會重新導向。

重寫

類型：Record<string, string>

定義自訂目錄 <-> URL 對應。有關更多詳細資訊，請參閱路由：路由重寫。

export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}

建置

srcDir

類型：字串
預設值：.

儲存 Markdown 頁面的目錄，相對於專案根目錄。另請參閱根目錄和來源目錄。

export default {
  srcDir: './src'
}

srcExclude

類型：字串
預設值：undefined

用於比對應排除為來源內容的 Markdown 檔案的 glob 模式。

export default {
  srcExclude: ['**/README.md', '**/TODO.md']
}

outDir

類型：字串
預設值：./.vitepress/dist

網站的建置輸出位置，相對於專案根目錄。

export default {
  outDir: '../public'
}

assetsDir

類型：字串
預設值：assets

指定要將產生之資源巢狀放置的目錄。路徑應位於 outDir 內，並相對於它解析。

export default {
  assetsDir: 'static'
}

cacheDir

類型：字串
預設值：./.vitepress/cache

快取檔案的目錄，相對於專案根目錄。另請參閱：cacheDir。

export default {
  cacheDir: './.vitepress/.vite'
}

ignoreDeadLinks

類型：boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]
預設值：false

設定為 true 時，VitePress 即使遇到失效連結也不會建置失敗。

設定為 'localhostLinks' 時，建置會在連結失效時失敗，但不會檢查 localhost 連結。

export default {
  ignoreDeadLinks: true
}

它也可以是精確網址字串、正規表示式模式或自訂篩選函式的陣列。

export default {
  ignoreDeadLinks: [
    // ignore exact url "/playground"
    '/playground',
    // ignore all localhost links
    /^https?:\/\/localhost/,
    // ignore all links include "/repl/""
    /\/repl\//,
    // custom function, ignore all links include "ignore"
    (url) => {
      return url.toLowerCase().includes('ignore')
    }
  ]
}

metaChunk 實驗

類型：boolean
預設值：false

設定為 true 時，將頁面元資料萃取到一個獨立的 JavaScript 塊，而不是將其內嵌在初始 HTML 中。這會縮小每個頁面的 HTML 負載，並讓頁面元資料可快取，因此當網站中有許多頁面時，可以減少伺服器頻寬。

mpa 實驗

類型：boolean
預設值：false

設定為 true 時，生產應用程式會以 MPA 模式建置。MPA 模式預設會傳送 0kb JavaScript，但代價是停用用戶端導覽，並需要明確選擇互動性。

主題

外觀

類型：boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions
預設：true

是否啟用暗色模式（透過將 .dark 類別新增到 <html> 元素）。

如果選項設定為 true，預設主題會由使用者的偏好色彩配置決定。
如果選項設定為 dark，主題預設為暗色，除非使用者手動切換。
如果選項設定為 false，使用者將無法切換主題。

此選項會注入一個內嵌指令碼，使用 vitepress-theme-appearance 金鑰從本機儲存空間還原使用者的設定。這可確保在頁面呈現之前套用 .dark 類別，以避免閃爍。

appearance.initialValue 只可以是 'dark' | undefined。不支援參照或取得器。

lastUpdated

類型：boolean
預設值：false

是否使用 Git 取得每個頁面的最後更新時間戳記。此時間戳記會包含在每個頁面的頁面資料中，可透過 useData 存取。

使用預設佈景主題時，啟用此選項會顯示每個頁面的最後更新時間。你可以透過 themeConfig.lastUpdatedText 選項自訂文字。

自訂

markdown

類型：MarkdownOption

設定 Markdown 解析器選項。VitePress 使用 Markdown-it 作為解析器，並使用 Shiki 來突顯語言語法。在此選項中，你可以傳遞各種 Markdown 相關選項以符合你的需求。

export default {
  markdown: {...}
}

查看類型宣告和 jsdocs 以取得所有可用的選項。

vite

類型：import('vite').UserConfig

將原始 Vite 設定傳遞給內部 Vite 開發伺服器/打包器。

export default {
  vite: {
    // Vite config options
  }
}

vue

類型：import('@vitejs/plugin-vue').Options

將原始 @vitejs/plugin-vue 選項傳遞給內部外掛實例。

export default {
  vue: {
    // @vitejs/plugin-vue options
  }
}

建置掛鉤

VitePress 建置掛鉤允許你為你的網站新增新的功能和行為

網站地圖
搜尋索引
PWA
傳送

buildEnd

類型：(siteConfig: SiteConfig) => Awaitable<void>

buildEnd 是建置 CLI 掛鉤，它會在建置 (SSG) 完成後但在 VitePress CLI 程序退出前執行。

export default {
  async buildEnd(siteConfig) {
    // ...
  }
}

postRender

類型：(context: SSGContext) => Awaitable<SSGContext | void>

postRender 是建置掛鉤，在 SSG 渲染完成時呼叫。它會允許你在 SSG 期間處理傳送內容。

export default {
  async postRender(context) {
    // ...
  }
}

interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead

類型：(context: TransformContext) => Awaitable<HeadConfig[]>

transformHead 是建置掛鉤，用於在產生每個頁面之前轉換標頭。它會允許你新增無法靜態新增到 VitePress 設定的標頭項目。你只需要傳回額外的項目，它們會自動與現有的項目合併。

警告

不要變更 context 內部的任何內容。

export default {
  async transformHead(context) {
    // ...
  }
}

interface TransformContext {
  page: string // e.g. index.md (relative to srcDir)
  assets: string[] // all non-js/css assets as fully resolved public URL
  siteConfig: SiteConfig
  siteData: SiteData
  pageData: PageData
  title: string
  description: string
  head: HeadConfig[]
  content: string
}

請注意，此掛鉤僅在靜態產生網站時呼叫。它不會在開發期間呼叫。如果你需要在開發期間新增動態標頭項目，你可以改用 transformPageData 掛鉤

export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      {
        name: 'og:title',
        content:
          pageData.frontmatter.layout === 'home'
            ? `VitePress`
            : `${pageData.title} | VitePress`
      }
    ])
  }
}

範例：新增標準網址 `<link>`

export default {
  transformPageData(pageData) {
    const canonicalUrl = `https://example.com/${pageData.relativePath}`
      .replace(/index\.md$/, '')
      .replace(/\.md$/, '.html')

    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'link',
      { rel: 'canonical', href: canonicalUrl }
    ])
  }
}

transformHtml

類型：(code: string, id: string, context: TransformContext) => Awaitable<string | void>

transformHtml 是在儲存至磁碟前轉換每個頁面內容的建置掛鉤。

警告

不要變更 context 內部的任何內容。此外，修改 html 內容可能會在執行階段造成水化問題。

export default {
  async transformHtml(code, id, context) {
    // ...
  }
}

transformPageData

類型：(pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>

transformPageData 是用來轉換每個頁面的 pageData 的掛鉤。你可以直接變更 pageData 或傳回將合併至頁面資料的已變更值。

警告

不要變更 context 內部的任何內容，且請小心這可能會影響開發伺服器的效能，特別是如果掛鉤中有一些網路要求或繁重的運算（例如產生圖片）。你可以檢查 process.env.NODE_ENV === 'production' 以進行條件式邏輯。

export default {
  async transformPageData(pageData, { siteConfig }) {
    pageData.contributors = await getPageContributors(pageData.relativePath)
  }

  // or return data to be merged
  async transformPageData(pageData, { siteConfig }) {
    return {
      contributors: await getPageContributors(pageData.relativePath)
    }
  }
}

interface TransformPageContext {
  siteConfig: SiteConfig
}

網站設定 ​

概觀 ​

設定解析 ​

設定 Intellisense ​

已輸入的主題設定 ​

Vite、Vue 和 Markdown 設定 ​

網站元資料 ​

標題 ​

titleTemplate ​

description ​

head ​

範例：新增 favicon ​

範例：新增 Google 字型 ​

範例：註冊服務工作人員 ​

範例：使用 Google Analytics ​

lang ​

base ​

路由 ​

cleanUrls ​

重寫 ​

建置 ​

srcDir ​

srcExclude ​

outDir ​

assetsDir ​

cacheDir ​

ignoreDeadLinks ​

metaChunk 實驗 ​

mpa 實驗 ​

主題 ​

外觀 ​

lastUpdated ​

自訂 ​

markdown ​

vite ​

vue ​

建置掛鉤 ​

buildEnd ​

postRender ​

transformHead ​

範例：新增標準網址 <link> ​

transformHtml ​

transformPageData ​