主题配置

默认主题提供了丰富的配置选项，可以轻松定制站点外观。

基础配置

logo

• 类型：string
• 默认值：无

站点 Logo，显示在导航栏左侧。

export default defineConfig({
  themeConfig: {
    logo: '/logo.svg'
  }
})

siteTitle

• 类型：string | false
• 默认值：title 配置

站点标题，设为 false 可隐藏。

export default defineConfig({
  themeConfig: {
    logo: '/logo.svg',
    siteTitle: '我的博客'
  }
})

appearance

• 类型：boolean | 'dark' | 'force-dark' | 'force-auto'
• 默认值：true

深色模式配置。

export default defineConfig({
  appearance: true  // 支持切换
})

export default defineConfig({
  appearance: 'dark' // 默认深色，可切换
})

export default defineConfig({
  appearance: 'force-dark' // 强制深色
})

导航配置

nav

• 类型：NavItem[]
• 默认值：无

导航栏配置。

export default defineConfig({
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      {
        text: '更多',
        items: [
          { text: '配置', link: '/config/' },
          { text: 'API', link: '/api/' }
        ]
      }
    ]
  }
})

NavItem 类型

interface NavItem {
  text: string
  link?: string
  items?: NavItem[]
  activeMatch?: string | RegExp
  target?: string
  rel?: string
  badge?: {
    text: string
    type?: 'info' | 'tip' | 'warning' | 'danger'
  }
}

带徽章的导航

nav: [
  { 
    text: '新功能', 
    link: '/new-feature',
    badge: { text: '新', type: 'tip' }
  }
]

侧边栏配置

sidebar

• 类型：Sidebar | SidebarMulti
• 默认值：无

侧边栏配置，支持多侧边栏。

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '开始',
        items: [
          { text: '介绍', link: '/guide/' },
          { text: '安装', link: '/guide/installation' }
        ]
      },
      {
        text: '进阶',
        collapsed: true,
        items: [
          { text: '配置', link: '/advanced/config' }
        ]
      }
    ]
  }
})

多侧边栏

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        { text: '指南', items: [...] }
      ],
      '/reference/': [
        { text: 'API 参考', items: [...] }
      ]
    }
  }
})

SidebarItem 类型

interface SidebarItem {
  text?: string
  link?: string
  items?: SidebarItem[]
  collapsed?: boolean
  base?: string
  badge?: BadgeConfig
}

折叠侧边栏

sidebar: [
  {
    text: '进阶',
    collapsed: true,  // 默认折叠
    items: [...]
  }
]

社交链接

socialLinks

• 类型：SocialLink[]
• 默认值：无

社交媒体链接。

export default defineConfig({
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/...' },
      { icon: 'twitter', link: 'https://twitter.com/...' },
      { icon: 'discord', link: 'https://discord.gg/...' }
    ]
  }
})

内置图标

图标	名称
github	GitHub
twitter	Twitter / X
discord	Discord
facebook	Facebook
instagram	Instagram
linkedin	LinkedIn
slack	Slack
youtube	YouTube
mastodon	Mastodon

自定义图标

socialLinks: [
  {
    icon: {
      svg: '<svg>...</svg>'
    },
    link: 'https://example.com'
  }
]

搜索配置

search

• 类型：SearchConfig
• 默认值：本地搜索

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        translations: {
          button: {
            buttonText: '搜索文档'
          }
        }
      }
    }
  }
})

Algolia 搜索

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    }
  }
})

编辑链接

editLink

• 类型：EditLinkConfig
• 默认值：无

export default defineConfig({
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: '在 GitHub 上编辑此页'
    }
  }
})

页脚配置

footer

• 类型：FooterConfig
• 默认值：无

export default defineConfig({
  themeConfig: {
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026'
    }
  }
})

大纲配置

outline

• 类型：OutlineConfig
• 默认值：{ level: 2, label: 'On this page' }

export default defineConfig({
  themeConfig: {
    outline: {
      level: [2, 3],  // 显示 h2 和 h3
      label: '目录导航'
    }
  }
})

文档页脚

docFooter

• 类型：DocFooterConfig
• 默认值：{ prev: 'Previous', next: 'Next' }

export default defineConfig({
  themeConfig: {
    docFooter: {
      prev: '上一页',
      next: '下一页'
    }
  }
})

最后更新

lastUpdated

• 类型：LastUpdatedConfig
• 默认值：{ text: 'Last updated' }

export default defineConfig({
  themeConfig: {
    lastUpdated: {
      text: '最后更新于',
      formatOptions: {
        dateStyle: 'full',
        timeStyle: 'short'
      }
    }
  }
})

本地化文本

returnToTopLabel

• 类型：string
• 默认值：'Return to top'

returnToTopLabel: '返回顶部'

sidebarMenuLabel

• 类型：string
• 默认值：'Menu'

sidebarMenuLabel: '菜单'

darkModeSwitchLabel

• 类型：string
• 默认值：'Appearance'

darkModeSwitchLabel: '主题'

首页配置

首页配置通过 frontmatter 设置：

---
layout: home
hero:
  name: VitePress
  text: 静态站点生成器
  tagline: 快速、简洁、强大
  image:
    src: /hero.png
    alt: Hero Image
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/
    - theme: alt
      text: GitHub
      link: https://github.com/vuejs/vitepress
features:
  - title: 🚀 极速
    details: 基于 Vite，毫秒级热更新
  - title: 🎨 灵活
    details: CSS 变量覆盖，完全定制
---

完整配置示例

// .vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的文档',
  description: '一个 VitePress 站点',
  
  themeConfig: {
    logo: '/logo.svg',
    siteTitle: '我的文档',
    
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ]
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/...' }
    ],
    
    search: {
      provider: 'local'
    },
    
    editLink: {
      pattern: 'https://github.com/.../edit/main/docs/:path',
      text: '编辑此页'
    },
    
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026'
    },
    
    outline: {
      level: [2, 3],
      label: '目录'
    },
    
    lastUpdated: {
      text: '最后更新'
    },
    
    returnToTopLabel: '返回顶部',
    sidebarMenuLabel: '菜单',
    darkModeSwitchLabel: '主题'
  }
})

参考链接

• 站点配置 - 站点级配置
• Frontmatter 配置 - 页面级配置
• 主题 API - 主题开发 API
• VitePress 官方主题配置文档