Skip to content

建立 2026-09-15 更新 2026-09-15

設定檔

設定檔固定在專案根目錄的 .vitepress/config.[js|ts|mjs|mts]。TypeScript 可直接使用，不必自己配 ts-node。

建議用官方提供的 defineConfig，才能有選項提示：

import { defineConfig } from 'vitepress'

export default defineConfig({
  lang: 'zh-Hant',
  title: '我的文件',
  description: '用 VitePress 建立的說明站',

  themeConfig: {
    // 頂欄、側欄、社群圖示、搜尋…屬於預設主題
  },
})

兩層設定

層級 管什麼 例子
應用／站台 任何主題都適用 lang、title、base、srcDir、markdown、vite
主題 themeConfig 預設主題的外觀與導覽 nav、sidebar、socialLinks、search、footer

把導覽寫在 themeConfig 外面不會生效；把 base 寫在 themeConfig 裡也不會生效。

一定要先認識的站台選項

  • base：佈署在子路徑時必填，例如 GitHub Pages 的 https://user.github.io/repo/ 要設 base: '/repo/'，結尾斜線不能省。細節見 佈署。
  • srcDir：Markdown 不跟 .vitepress 同一層時才需要改。
  • cleanUrls：網址要不要 .html。
  • markdown：行號、數學公式、額外 markdown-it 外掛。
  • vite：把 Vite 外掛（例如分析、SVG）接進來，不必另開 vite.config.js。

單頁還能用 frontmatter 覆寫標題、layout 等。完整列表見〈站點配置〉與〈frontmatter〉。