Default Theme Config

Complete reference for configuring the VitePress default theme.

Overview

The default theme configuration is defined in the themeConfig section of your VitePress config file.

javascript

// .vitepress/config.js
export default {
  themeConfig: {
    // Theme configuration options
  }
}

Site Branding

Logo Configuration

javascript

export default {
  themeConfig: {
    // Simple logo
    logo: '/logo.svg',
    
    // Logo with light/dark variants
    logo: {
      light: '/logo-light.svg',
      dark: '/logo-dark.svg'
    },
    
    // Custom site title
    siteTitle: 'My Documentation',
    
    // Hide site title (show only logo)
    siteTitle: false
  }
}

Favicon

javascript

export default {
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
    ['link', { rel: 'apple-touch-icon', href: '/apple-touch-icon.png' }]
  ]
}

javascript

export default {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'Config', link: '/config/', activeMatch: '/config/' },
      
      // Dropdown menu
      {
        text: 'Dropdown',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' }
        ]
      }
    ]
  }
}

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>...</svg>'
        },
        link: 'https://example.com'
      }
    ]
  }
}

javascript

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' }
        ]
      }
    ]
  }
}

javascript

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

javascript

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Getting Started',
        collapsed: false,
        items: [
          { text: 'Introduction', link: '/introduction' }
        ]
      },
      {
        text: 'Advanced',
        collapsed: true,
        items: [
          { text: 'Customization', link: '/customization' }
        ]
      }
    ]
  }
}

Search

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

javascript

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      }
    }
  }
}

javascript

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

javascript

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

Edit Links

GitHub Edit Links

javascript

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

Conditional Edit Links

javascript

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

Last Updated

Enable Last Updated

javascript

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

Outline

javascript

export default {
  themeConfig: {
    outline: {
      level: [2, 3],
      label: 'On this page'
    }
  }
}

Deep Outline

javascript

export default {
  themeConfig: {
    outline: 'deep' // Show all heading levels
  }
}

Appearance

Dark Mode

javascript

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

Carbon Ads

Basic Configuration

javascript

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

Localization

Multi-language Configuration

javascript

export default {
  locales: {
    root: {
      themeConfig: {
        nav: [
          { text: 'Home', link: '/' },
          { text: 'Guide', link: '/guide/' }
        ]
      }
    },
    zh: {
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '指南', link: '/zh/guide/' }
        ],
        outlineTitle: '页面导航',
        lastUpdatedText: '最后更新于',
        editLinkText: '在 GitHub 上编辑此页面'
      }
    }
  }
}

Advanced Options

Return to Top

javascript

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

External Link Icon

javascript

export default {
  themeConfig: {
    externalLinkIcon: true
  }
}

Custom CSS Variables

css

:root {
  --vp-c-brand-1: #646cff;
  --vp-c-brand-2: #747bff;
  --vp-c-brand-3: #535bf2;
}

Complete Example

javascript

// .vitepress/config.js
export default {
  title: 'My Documentation',
  description: 'A comprehensive documentation site',
  
  themeConfig: {
    // Site branding
    logo: '/logo.svg',
    siteTitle: 'My Docs',
    
    // Navigation
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      {
        text: 'Resources',
        items: [
          { text: 'Examples', link: '/examples/' },
          { text: 'FAQ', link: '/faq/' }
        ]
      }
    ],
    
    // Sidebar
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/' },
            { text: 'Installation', link: '/guide/installation' },
            { text: 'Quick Start', link: '/guide/quick-start' }
          ]
        },
        {
          text: 'Advanced',
          collapsed: true,
          items: [
            { text: 'Configuration', link: '/guide/configuration' },
            { text: 'Customization', link: '/guide/customization' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'Overview', link: '/api/' },
            { text: 'Methods', link: '/api/methods' },
            { text: 'Properties', link: '/api/properties' }
          ]
        }
      ]
    },
    
    // Social links
    socialLinks: [
      { icon: 'github', link: 'https://github.com/username/repository' },
      { icon: 'twitter', link: 'https://twitter.com/username' }
    ],
    
    // Search
    search: {
      provider: 'local'
    },
    
    // Footer
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2024 My Company'
    },
    
    // Edit links
    editLink: {
      pattern: 'https://github.com/username/repository/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    },
    
    // Last updated
    lastUpdated: {
      text: 'Updated at',
      formatOptions: {
        dateStyle: 'short',
        timeStyle: 'medium'
      }
    },
    
    // Outline
    outline: {
      level: [2, 3],
      label: 'On this page'
    },
    
    // Carbon Ads
    carbonAds: {
      code: 'CEBDT27Y',
      placement: 'vitepressdevcom'
    }
  }
}

TypeScript Support

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

Performance

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

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

Default Theme Config ​

Overview ​

Site Branding ​

Logo Configuration ​

Favicon ​

Navigation ​

Top Navigation ​

Social Links ​

Sidebar ​

Basic Sidebar ​

Multi-Sidebar ​

Collapsible Sidebar ​

Search ​

Local Search ​

Algolia Search ​

Footer ​

Basic Footer ​

Rich Footer ​

Edit Links ​

GitHub Edit Links ​

Conditional Edit Links ​

Last Updated ​

Enable Last Updated ​

Outline ​

Table of Contents ​

Deep Outline ​

Appearance ​

Dark Mode ​

Carbon Ads ​

Basic Configuration ​

Localization ​

Multi-language Configuration ​

Advanced Options ​

Return to Top ​

External Link Icon ​

Custom CSS Variables ​

Complete Example ​

TypeScript Support ​

Best Practices ​

Navigation Design ​

Sidebar Organization ​

Performance ​

Accessibility ​

Maintenance ​

Default Theme Config

Overview

Site Branding

Logo Configuration

Favicon

Navigation

Top Navigation

Social Links

Sidebar

Basic Sidebar

Multi-Sidebar

Collapsible Sidebar

Search

Local Search

Algolia Search

Footer

Basic Footer

Rich Footer

Edit Links

GitHub Edit Links

Conditional Edit Links

Last Updated

Enable Last Updated

Outline

Table of Contents

Deep Outline

Appearance

Dark Mode

Carbon Ads

Basic Configuration

Localization

Multi-language Configuration

Advanced Options

Return to Top

External Link Icon

Custom CSS Variables

Complete Example

TypeScript Support

Best Practices

Navigation Design

Sidebar Organization

Performance

Accessibility

Maintenance