VitePress

English

简体中文

English

简体中文

Appearance

Official Themes ​

Learn about the official themes provided by VitePress and how to use them effectively.

Default Theme ​

The default theme is the primary theme that ships with VitePress, providing a clean and professional appearance suitable for documentation sites.

Features ​

Core Features ​

  • Responsive Design: Adapts to all screen sizes
  • Dark Mode: Built-in dark/light theme toggle
  • Navigation: Flexible navbar and sidebar configuration
  • Search: Integrated local search functionality
  • Internationalization: Multi-language support
  • Accessibility: WCAG compliant design

Advanced Features ​

  • Custom Containers: Callouts, warnings, and info boxes
  • Code Highlighting: Syntax highlighting with Shiki
  • Math Support: LaTeX math expressions
  • Mermaid Diagrams: Flowcharts and diagrams
  • Team Pages: Showcase team members
  • Home Page: Customizable landing page

Installation ​

The default theme is included with VitePress by default:

bash
npm install vitepress

Basic Configuration ​

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

export default defineConfig({
  title: 'My Documentation',
  description: 'A VitePress site with default theme',
  
  themeConfig: {
    // Theme configuration options
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' }
    ],
    
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/guide/introduction' },
          { text: 'Getting Started', link: '/guide/getting-started' }
        ]
      }
    ],
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ]
  }
})

Theme Configuration Options ​

Site Branding ​

js
export default {
  themeConfig: {
    // Site title in navbar
    siteTitle: 'My Documentation',
    
    // Logo image
    logo: '/logo.svg',
    
    // Logo with different images for light/dark mode
    logo: {
      light: '/logo-light.svg',
      dark: '/logo-dark.svg'
    }
  }
}
js
export default {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      {
        text: 'Dropdown',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' }
        ]
      }
    ]
  }
}
js
export default {
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Introduction', link: '/guide/introduction' },
            { text: 'Getting Started', link: '/guide/getting-started' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'Configuration', link: '/api/configuration' },
            { text: 'Runtime API', link: '/api/runtime-api' }
          ]
        }
      ]
    }
  }
}
js
export default {
  themeConfig: {
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2023-present Evan You'
    }
  }
}
js
export default {
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: 'https://twitter.com/vuejs' },
      { icon: 'discord', link: 'https://discord.gg/vue' }
    ]
  }
}

Home Page Configuration ​

Create a custom home page with hero section and features:

yaml
---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator
  tagline: Simple, powerful, and performant. Meet the modern SSG framework you've always wanted.
  image:
    src: /logo-large.png
    alt: VitePress
  actions:
    - theme: brand
      text: Get Started
      link: /guide/getting-started
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress

features:
  - title: "Vite: The DX that can't be beat"
    details: Feel the speed of Vite. Instant server start and lightning fast HMR that stays fast regardless of the app size.
    icon: ⚡
  - title: Designed to be simplicity first
    details: With Markdown-centered content, it's built to help you focus on writing and deployed with minimum configuration.
    icon: 📝
  - title: Power of Vue meets Markdown
    details: Enhance your content with all the features of Vue in Markdown, while being able to customize your site with Vue.
    icon: 🚀
---

Customization ​

CSS Variables ​

Customize the theme appearance using CSS variables:

css
/* .vitepress/theme/custom.css */
:root {
  /* Colors */
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
  --vp-c-brand-lighter: #9499ff;
  --vp-c-brand-lightest: #bcc0ff;
  --vp-c-brand-dark: #535bf2;
  --vp-c-brand-darker: #454ce1;
  
  /* Typography */
  --vp-font-family-base: 'Inter', sans-serif;
  --vp-font-family-mono: 'Fira Code', monospace;
  
  /* Layout */
  --vp-layout-max-width: 1440px;
  --vp-sidebar-width: 272px;
  --vp-nav-height: 64px;
}

Custom Components ​

Extend the theme with custom components:

js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import CustomComponent from './components/CustomComponent.vue'
import './custom.css'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('CustomComponent', CustomComponent)
  }
}

Layout Slots ​

Use layout slots to add custom content:

vue
<!-- .vitepress/theme/Layout.vue -->
<template>
  <Layout>
    <template #nav-bar-title-after>
      <span class="version-badge">v1.0</span>
    </template>
    
    <template #nav-bar-content-after>
      <div class="custom-nav-content">
        <!-- Custom navigation content -->
      </div>
    </template>
    
    <template #sidebar-nav-before>
      <div class="sidebar-header">
        <!-- Custom sidebar header -->
      </div>
    </template>
    
    <template #page-top>
      <div class="page-header">
        <!-- Custom page header -->
      </div>
    </template>
    
    <template #page-bottom>
      <div class="page-footer">
        <!-- Custom page footer -->
      </div>
    </template>
  </Layout>
</template>

<script setup>
import DefaultTheme from 'vitepress/theme'
const { Layout } = DefaultTheme
</script>

Advanced Features ​

Search Configuration ​

js
export default {
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        translations: {
          button: {
            buttonText: 'Search',
            buttonAriaLabel: 'Search'
          },
          modal: {
            noResultsText: 'No results for',
            resetButtonTitle: 'Clear search',
            footer: {
              selectText: 'to select',
              navigateText: 'to navigate',
              closeText: 'to close'
            }
          }
        }
      }
    }
  }
}
js
export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

Last Updated ​

js
export default {
  lastUpdated: true,
  themeConfig: {
    lastUpdatedText: 'Last updated'
  }
}

Carbon Ads ​

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

Internationalization ​

Configure multiple languages:

js
export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    zh: {
      label: '中文',
      lang: 'zh-CN',
      link: '/zh/'
    }
  },
  
  themeConfig: {
    i18nRouting: true,
    
    localeLinks: {
      text: 'Languages',
      items: [
        { text: 'English', link: '/' },
        { text: '中文', link: '/zh/' }
      ]
    }
  }
}

Team Pages ​

Create beautiful team pages to showcase contributors:

yaml
---
layout: page
---

<script setup>
import {
  VPTeamPage,
  VPTeamPageTitle,
  VPTeamMembers
} from 'vitepress/theme'

const members = [
  {
    avatar: 'https://www.github.com/yyx990803.png',
    name: 'Evan You',
    title: 'Creator',
    links: [
      { icon: 'github', link: 'https://github.com/yyx990803' },
      { icon: 'twitter', link: 'https://twitter.com/youyuxi' }
    ]
  }
]
</script>

<VPTeamPage>
  <VPTeamPageTitle>
    <template #title>Our Team</template>
    <template #lead>Meet the people behind this project.</template>
  </VPTeamPageTitle>
  <VPTeamMembers :members="members" />
</VPTeamPage>

Theme Migration ​

From VuePress ​

Key differences when migrating from VuePress:

  1. Configuration: Different config structure
  2. Components: New component names and APIs
  3. Styling: CSS variable system
  4. Plugins: Different plugin architecture

Migration Steps ​

  1. Update Dependencies:

    bash
    npm uninstall vuepress
npm install vitepress

  2. Update Configuration:

    js
    // Old VuePress config
module.exports = {
  title: 'My Site',
  themeConfig: {
    nav: [...],
    sidebar: [...]
  }
}

// New VitePress config
export default {
  title: 'My Site',
  themeConfig: {
    nav: [...],
    sidebar: [...]
  }
}

  3. Update Frontmatter:

    yaml
    # Old
---
sidebar: auto
---

# New
---
outline: deep
---

Performance Optimization ​

Bundle Analysis ​

bash
# Build with bundle analysis
npm run build -- --analyze

Code Splitting ​

js
// Dynamic imports for large components
const HeavyComponent = defineAsyncComponent(() => 
  import('./components/HeavyComponent.vue')
)

Image Optimization ​

markdown
<!-- Use optimized images -->
![Alt text](/images/optimized-image.webp)

<!-- Lazy loading -->
<img src="/images/hero.jpg" loading="lazy" alt="Hero image" />

Troubleshooting ​

Common Issues ​

Build Errors ​

  • Check Node.js version compatibility
  • Verify all dependencies are installed
  • Clear cache and node_modules

Styling Issues ​

  • Ensure CSS variables are properly defined
  • Check for conflicting styles
  • Verify import paths
  • Validate sidebar configuration
  • Check file paths and links
  • Ensure proper frontmatter

Debug Mode ​

bash
# Enable debug mode
DEBUG=vitepress:* npm run dev

Performance Issues ​

  • Optimize images and assets
  • Use code splitting
  • Enable compression
  • Implement caching strategies

Best Practices ​

Content Organization ​

  • Use clear folder structure
  • Implement consistent naming
  • Organize by feature or topic
  • Maintain proper hierarchy

SEO Optimization ​

  • Use descriptive titles and descriptions
  • Implement proper heading structure
  • Add meta tags and structured data
  • Generate sitemaps

Accessibility ​

  • Use semantic HTML
  • Provide alt text for images
  • Ensure keyboard navigation
  • Maintain color contrast

Performance ​

  • Optimize images and assets
  • Use lazy loading
  • Implement code splitting
  • Monitor bundle size

Future Roadmap ​

Upcoming Features ​

  • Enhanced theme customization
  • Improved performance
  • Better accessibility
  • Advanced internationalization

Community Contributions ​

  • Theme marketplace
  • Plugin ecosystem
  • Documentation improvements
  • Bug fixes and enhancements

The default theme continues to evolve with regular updates and improvements. Stay updated with the latest releases for new features and optimizations.

VitePress Development Guide

Copyright © 2025 mmwk.cn