Theme Configuration

Learn how to configure the VitePress default theme with comprehensive customization options.

Basic Theme Configuration

Theme Config Structure

Configure the theme in your config file:

javascript

// .vitepress/config.js
export default {
  themeConfig: {
    // Site title in navigation
    siteTitle: 'My Docs',
    
    // Logo configuration
    logo: '/logo.svg',
    
    // Navigation menu
    nav: [...],
    
    // Sidebar configuration
    sidebar: {...},
    
    // Footer configuration
    footer: {...}
  }
}

Logo Configuration

Configure site logo:

javascript

export default {
  themeConfig: {
    // Simple logo
    logo: '/logo.svg',
    
    // Logo with different versions for light/dark mode
    logo: {
      light: '/logo-light.svg',
      dark: '/logo-dark.svg'
    },
    
    // Disable site title text (show only logo)
    siteTitle: false,
    
    // Custom site title (overrides config.title)
    siteTitle: 'Custom Title'
  }
}

Configure the main navigation menu:

javascript

export default {
  themeConfig: {
    nav: [
      // Simple link
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      
      // Link with active match pattern
      { text: 'Config', link: '/config/', activeMatch: '/config/' },
      
      // Dropdown menu
      {
        text: 'Dropdown',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' },
          { text: 'Item C', link: '/item-c' }
        ]
      },
      
      // Nested dropdown
      {
        text: 'Resources',
        items: [
          {
            text: 'Documentation',
            items: [
              { text: 'Getting Started', link: '/docs/getting-started' },
              { text: 'API Reference', link: '/docs/api' }
            ]
          },
          {
            text: 'Community',
            items: [
              { text: 'Discord', link: 'https://discord.gg/example' },
              { text: 'GitHub', link: 'https://github.com/example' }
            ]
          }
        ]
      },
      
      // External link
      { text: 'GitHub', link: 'https://github.com/vuejs/vitepress' }
    ]
  }
}

Add social media links to navigation:

javascript

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' },
      
      // Custom SVG icon
      {
        icon: {
          svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Custom</title><path d="..."/></svg>'
        },
        link: 'https://example.com'
      }
    ]
  }
}

Configure sidebar navigation:

javascript

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
          { text: 'Configuration', link: '/configuration' }
        ]
      },
      {
        text: 'Advanced',
        items: [
          { text: 'Customization', link: '/customization' },
          { text: 'Deployment', link: '/deployment' }
        ]
      }
    ]
  }
}

Different sidebars for different sections:

javascript

export default {
  themeConfig: {
    sidebar: {
      // Sidebar for /guide/ section
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Introduction', link: '/guide/' },
            { text: 'Getting Started', link: '/guide/getting-started' },
            { text: 'Configuration', link: '/guide/configuration' }
          ]
        }
      ],
      
      // Sidebar for /api/ section
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'Overview', link: '/api/' },
            { text: 'Methods', link: '/api/methods' },
            { text: 'Properties', link: '/api/properties' }
          ]
        }
      ]
    }
  }
}

Create collapsible sidebar sections:

javascript

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Getting Started',
        collapsed: false, // Expanded by default
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Installation', link: '/installation' }
        ]
      },
      {
        text: 'Advanced Topics',
        collapsed: true, // Collapsed by default
        items: [
          { text: 'Customization', link: '/customization' },
          { text: 'Plugins', link: '/plugins' }
        ]
      }
    ]
  }
}

Search Configuration

Local Search

Configure built-in local search:

javascript

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'
            }
          }
        }
      }
    }
  }
}

Algolia Search

Configure Algolia DocSearch:

javascript

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        
        // Optional parameters
        searchParameters: {
          facetFilters: ['tags:guide']
        },
        
        // Localization
        locales: {
          zh: {
            placeholder: '搜索文档',
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              }
            }
          }
        }
      }
    }
  }
}

Configure site footer:

javascript

export default {
  themeConfig: {
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2024 My Company'
    }
  }
}

Footer with HTML content:

javascript

export default {
  themeConfig: {
    footer: {
      message: 'Released under the <a href="https://github.com/example/license">MIT License</a>.',
      copyright: 'Copyright © 2024-present <a href="https://example.com">My Company</a>'
    }
  }
}

Edit Link Configuration

GitHub Edit Links

Enable edit links for GitHub:

javascript

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/username/repository/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

GitLab Edit Links

Configure for GitLab:

javascript

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://gitlab.com/username/repository/-/edit/main/docs/:path',
      text: 'Edit this page on GitLab'
    }
  }
}

Conditional Edit Links

Show edit links only for specific pages:

javascript

export default {
  themeConfig: {
    editLink: {
      pattern: ({ filePath }) => {
        if (filePath.startsWith('api/')) {
          return `https://github.com/username/repository/edit/main/docs/${filePath}`
        }
        return false // No edit link for other pages
      },
      text: 'Suggest changes'
    }
  }
}

Last Updated Configuration

Enable Last Updated

Show last updated timestamp:

javascript

export default {
  lastUpdated: true,
  
  themeConfig: {
    lastUpdated: {
      text: 'Updated at',
      formatOptions: {
        dateStyle: 'full',
        timeStyle: 'medium'
      }
    }
  }
}

Custom Last Updated Format

Customize the format:

javascript

export default {
  themeConfig: {
    lastUpdated: {
      text: 'Last modified',
      formatOptions: {
        dateStyle: 'short',
        timeStyle: 'short'
      }
    }
  }
}

Outline Configuration

Configure the right sidebar outline:

javascript

export default {
  themeConfig: {
    outline: {
      level: [2, 3], // Show h2 and h3 headings
      label: 'On this page'
    }
  }
}

Deep Outline

Show all heading levels:

javascript

export default {
  themeConfig: {
    outline: 'deep' // Equivalent to [2, 3, 4, 5, 6]
  }
}

Disable Outline

Disable the outline:

javascript

export default {
  themeConfig: {
    outline: false
  }
}

Appearance Configuration

Dark Mode

Configure dark mode toggle:

javascript

export default {
  appearance: true, // Enable dark mode toggle
  
  themeConfig: {
    // Custom dark mode toggle text
    darkModeSwitchLabel: 'Appearance',
    lightModeSwitchTitle: 'Switch to light theme',
    darkModeSwitchTitle: 'Switch to dark theme'
  }
}

Force Appearance

Force light or dark mode:

javascript

export default {
  appearance: 'dark', // Force dark mode
  // or
  appearance: false // Disable dark mode entirely
}

Return to Top

Configure Return to Top Button

javascript

export default {
  themeConfig: {
    returnToTopLabel: 'Return to top'
  }
}

External Link Icon

Configure External Link Behavior

javascript

export default {
  themeConfig: {
    externalLinkIcon: true // Show icon for external links
  }
}

Advanced Theme Configuration

Custom CSS Variables

Override theme variables:

javascript

export default {
  themeConfig: {
    // This doesn't directly set CSS variables,
    // but you can use it in your custom CSS
    customCssVars: {
      '--vp-c-brand-1': '#646cff',
      '--vp-c-brand-2': '#747bff'
    }
  }
}

Responsive Breakpoints

Configure responsive behavior:

javascript

export default {
  themeConfig: {
    // These are handled by CSS, but you can reference them
    breakpoints: {
      mobile: '768px',
      tablet: '1024px',
      desktop: '1280px'
    }
  }
}

Localization

Multi-language Theme Config

Different theme configurations per locale:

javascript

export default {
  locales: {
    root: {
      themeConfig: {
        nav: [
          { text: 'Home', link: '/' },
          { text: 'Guide', link: '/guide/' }
        ],
        sidebar: {
          '/guide/': [
            { text: 'Introduction', link: '/guide/' }
          ]
        },
        footer: {
          message: 'Released under the MIT License.',
          copyright: 'Copyright © 2024 My Company'
        }
      }
    },
    
    zh: {
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '指南', link: '/zh/guide/' }
        ],
        sidebar: {
          '/zh/guide/': [
            { text: '介绍', link: '/zh/guide/' }
          ]
        },
        footer: {
          message: '基于 MIT 许可发布',
          copyright: '版权所有 © 2024 我的公司'
        },
        
        // Localized UI text
        outlineTitle: '页面导航',
        lastUpdatedText: '最后更新于',
        editLinkText: '在 GitHub 上编辑此页面',
        returnToTopLabel: '回到顶部'
      }
    }
  }
}

Custom Components

Registering Custom Components

Add custom components to theme:

javascript

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

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

Using Components in Config

Reference components in configuration:

javascript

export default {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { 
        text: 'Custom', 
        link: '/custom',
        // This would need custom theme implementation
        component: 'CustomNavItem'
      }
    ]
  }
}

Validation and Testing

Configuration Validation

Validate theme configuration:

javascript

function validateThemeConfig(themeConfig) {
  const errors = []
  
  // Validate navigation
  if (themeConfig.nav) {
    themeConfig.nav.forEach((item, index) => {
      if (!item.text || !item.link) {
        errors.push(`Navigation item ${index} missing text or link`)
      }
    })
  }
  
  // Validate sidebar
  if (themeConfig.sidebar) {
    // Add sidebar validation logic
  }
  
  if (errors.length > 0) {
    console.warn('Theme configuration issues:', errors)
  }
  
  return themeConfig
}

export default {
  themeConfig: validateThemeConfig({
    nav: [
      { text: 'Home', link: '/' }
    ]
  })
}

TypeScript Support

Use TypeScript for better theme config:

typescript

import { defineConfig, type DefaultTheme } from 'vitepress'

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/' },
            { text: 'Installation', link: '/guide/installation' }
          ]
        }
      ]
    }
  } satisfies DefaultTheme.Config
})

Best Practices

Keep navigation simple and intuitive
Use consistent naming conventions
Group related items together
Provide clear visual hierarchy

Organize content logically
Use collapsible groups for large sections
Provide clear section titles
Consider user journey and flow

Search Optimization

Choose appropriate search provider
Configure search parameters properly
Test search functionality regularly
Monitor search analytics

Performance

Minimize navigation complexity
Optimize images and icons
Use appropriate caching strategies
Test on various devices and connections

Accessibility

Ensure keyboard navigation works
Use proper ARIA labels
Maintain sufficient color contrast
Test with screen readers

Maintenance

Keep configuration organized
Document custom configurations
Regular testing across browsers
Monitor user feedback and analytics

Theme Configuration ​

Basic Theme Configuration ​

Theme Config Structure ​

Logo Configuration ​

Navigation Configuration ​

Top Navigation ​

Social Links ​

Sidebar Configuration ​

Basic Sidebar ​

Multi-Sidebar ​

Collapsible Sidebar Groups ​

Search Configuration ​

Local Search ​

Algolia Search ​

Footer Configuration ​

Basic Footer ​

Rich Footer ​

Edit Link Configuration ​

GitHub Edit Links ​

GitLab Edit Links ​

Conditional Edit Links ​

Last Updated Configuration ​

Enable Last Updated ​

Custom Last Updated Format ​

Outline Configuration ​

Table of Contents ​

Deep Outline ​

Disable Outline ​

Appearance Configuration ​

Dark Mode ​

Force Appearance ​

Return to Top ​

Configure Return to Top Button ​

External Link Icon ​

Configure External Link Behavior ​

Advanced Theme Configuration ​

Custom CSS Variables ​

Responsive Breakpoints ​

Localization ​

Multi-language Theme Config ​

Custom Components ​

Registering Custom Components ​

Using Components in Config ​

Validation and Testing ​

Configuration Validation ​

TypeScript Support ​

Best Practices ​

Navigation Design ​

Sidebar Organization ​

Search Optimization ​

Performance ​

Accessibility ​

Maintenance ​

Theme Configuration

Basic Theme Configuration

Theme Config Structure

Logo Configuration

Navigation Configuration

Top Navigation

Social Links

Sidebar Configuration

Basic Sidebar

Multi-Sidebar

Collapsible Sidebar Groups

Search Configuration

Local Search

Algolia Search

Footer Configuration

Basic Footer

Rich Footer

Edit Link Configuration

GitHub Edit Links

GitLab Edit Links

Conditional Edit Links

Last Updated Configuration

Enable Last Updated

Custom Last Updated Format

Outline Configuration

Table of Contents

Deep Outline

Disable Outline

Appearance Configuration

Dark Mode

Force Appearance

Return to Top

Configure Return to Top Button

External Link Icon

Configure External Link Behavior

Advanced Theme Configuration

Custom CSS Variables

Responsive Breakpoints

Localization

Multi-language Theme Config

Custom Components

Registering Custom Components

Using Components in Config

Validation and Testing

Configuration Validation

TypeScript Support

Best Practices

Navigation Design

Sidebar Organization

Search Optimization

Performance

Accessibility

Maintenance