默认主题配置

VitePress 提供了一个精心设计的默认主题，开箱即用，同时支持高度定制。

版本说明

• 本文档基于 VitePress v1.0.0+ 编写
• 大部分配置选项在 v0.20.0+ 即可使用
• 部分新增配置在后续版本中引入

主题继承

默认主题是 VitePress 的内置主题，无需额外配置即可使用。

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

export default defineConfig({
  // 不指定 themeConfig 时使用默认配置
  themeConfig: {
    // 在此覆盖默认配置
  }
})

外观定制

主题切换

export default defineConfig({
  // 启用深色/浅色模式切换
  appearance: true,
  
  // 强制深色模式
  // appearance: 'force-dark',
  
  // 强制浅色模式
  // appearance: 'force-light',
  
  // 禁用主题切换
  // appearance: false
})

图标与 Logo

export default defineConfig({
  themeConfig: {
    // Favicon
    // 需要在 docs/public/ 目录下放置 favicon.ico
    
    // Logo
    logo: '/logo.svg',
    
    // 分离深色/浅色模式 Logo (v1.0.0+)
    logo: {
      light: '/logo-light.svg',
      dark: '/logo-dark.svg'
    }
  }
})

版本兼容性

配置项	最低版本	说明
appearance	v0.20.0	主题切换功能
logo	v0.20.0	Logo 配置
logo.light/dark	v1.0.0	分离深浅色 Logo
nav	v0.20.0	导航配置
sidebar	v0.20.0	侧边栏配置
outline.level	v1.0.0	多级大纲配置
search.provider: 'local'	v1.0.0	本地搜索
socialLinks	v0.20.0	社交链接
editLink.pattern	v0.20.0	编辑链接
lastUpdated	v0.20.0	最后更新时间
footer	v0.20.0	页脚配置

导航与布局

顶部导航

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

侧边栏

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '指南',
        items: [
          { text: '介绍', link: '/guide/' }
        ]
      }
    ]
  }
})

页脚

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

文档页面

页面导航（大纲）

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

上一页/下一页

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

编辑链接

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

最后更新时间

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

搜索功能

本地搜索

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        detailedView: true,
        miniSearch: {
          searchOptions: {
            fuzzy: 0.2
          }
        }
      }
    }
  }
})

Algolia 搜索

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

国际化文本

export default defineConfig({
  themeConfig: {
    // 返回顶部
    returnToTopLabel: '返回顶部',
    
    // 侧边栏菜单
    sidebarMenuLabel: '菜单',
    
    // 主题切换
    darkModeSwitchLabel: '主题',
    lightModeSwitchTitle: '切换到浅色模式',
    darkModeSwitchTitle: '切换到深色模式'
  }
})

社交链接

export default defineConfig({
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: 'https://twitter.com/vuejs' },
      { icon: 'discord', link: 'https://discord.gg/vue' },
      { icon: 'youtube', link: 'https://youtube.com/vuejs' },
      { icon: 'instagram', link: 'https://instagram.com/vuejs' },
      { icon: 'linkedin', link: 'https://linkedin.com/company/vuejs' },
      { icon: 'slack', link: 'https://vueslack.slack.com' }
    ]
  }
})

自定义图标

socialLinks: [
  {
    icon: {
      svg: '<svg viewBox="0 0 24 24" fill="currentColor"><path d="..."/></svg>'
    },
    link: 'https://example.com',
    ariaLabel: '自定义链接'
  }
]

跳转链接

为首页底部添加跳转链接：

export default defineConfig({
  themeConfig: {
    navLinks: [
      { text: '开始学习', link: '/guide/' },
      { text: 'GitHub', link: 'https://github.com' }
    ]
  }
})

完整配置示例

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'VitePress 学习指南',
  description: '从零开始学习 VitePress',
  lang: 'zh-CN',
  appearance: true,
  lastUpdated: true,
  cleanUrls: true,
  
  themeConfig: {
    logo: '/logo.svg',
    siteTitle: 'VitePress 学习指南',
    
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/api/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: '入门指南',
          items: [
            { text: '介绍', link: '/guide/' }
          ]
        }
      ]
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ],
    
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026-present'
    },
    
    outline: {
      label: '页面导航',
      level: [2, 3]
    },
    
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: '编辑此页'
    },
    
    docFooter: {
      prev: '上一页',
      next: '下一页'
    },
    
    lastUpdated: {
      text: '最后更新于'
    },
    
    returnToTopLabel: '返回顶部',
    sidebarMenuLabel: '菜单',
    darkModeSwitchLabel: '主题',
    
    search: {
      provider: 'local'
    }
  }
})

下一步

学习如何 自定义主题 来完全控制站点外观。