Default Theme Configuration

Configure VitePress default theme options

Default Theme Configuration

The default theme configuration is set via the themeConfig option in your config file. These options control the appearance and behavior of the default VitePress theme.

export default defineConfig({
  themeConfig: {
    logo: '/logo.svg',
    nav: [...],
    sidebar: {...}
  }
})

These options only apply to the default theme. Custom themes receive this config object but may handle it differently.

Site Branding

logo

logo · ThemeableImage

Logo file displayed in the nav bar, before the site title.

Simple Logo

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

With Alt Text

export default defineConfig({
  themeConfig: {
    logo: {
      src: '/logo.svg',
      alt: 'My Company Logo'
    }
  }
})

Light/Dark Mode

export default defineConfig({
  themeConfig: {
    logo: {
      light: '/logo-light.svg',
      dark: '/logo-dark.svg',
      alt: 'Logo'
    }
  }
})

type ThemeableImage =
  | string
  | { src: string; alt?: string }
  | { light: string; dark: string; alt?: string }

logoLink

logoLink · string | { link?: string; rel?: string; target?: string }

Override the link when clicking the logo.

export default defineConfig({
  themeConfig: {
    logoLink: 'https://example.com'
  }
})

// Or with attributes
export default defineConfig({
  themeConfig: {
    logoLink: {
      link: 'https://example.com',
      target: '_blank',
      rel: 'noopener'
    }
  }
})

siteTitle

siteTitle · string | false

Customize the site title in the nav bar. Set to false to hide it (useful when logo contains text).

export default defineConfig({
  themeConfig: {
    siteTitle: 'My Custom Title'
  }
})

// Hide title
export default defineConfig({
  themeConfig: {
    siteTitle: false
  }
})

Navigation

nav

nav · NavItem[]

Navigation menu items displayed in the header.

Simple Links

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: 'Changelog', link: '/changelog' }
    ]
  }
})

Dropdown Menu

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      {
        text: 'Reference',
        items: [
          { text: 'API', link: '/api/' },
          { text: 'Config', link: '/config/' },
          { text: 'CLI', link: '/cli/' }
        ]
      }
    ]
  }
})

Nested Dropdown

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Docs',
        items: [
          {
            text: 'Getting Started',
            items: [
              { text: 'Introduction', link: '/intro' },
              { text: 'Installation', link: '/install' }
            ]
          },
          {
            text: 'Advanced',
            items: [
              { text: 'Deployment', link: '/deploy' },
              { text: 'SSR', link: '/ssr' }
            ]
          }
        ]
      }
    ]
  }
})

Active State

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Guide',
        link: '/guide/',
        activeMatch: '/guide/' // Regex pattern
      },
      {
        text: 'API',
        link: '/api/',
        activeMatch: '^/api/'
      }
    ]
  }
})

Dynamic Links

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Version',
        link: (pageData) => {
          return `/v${pageData.frontmatter.version}/`
        }
      }
    ]
  }
})

type NavItem = NavItemWithLink | NavItemWithChildren

interface NavItemWithLink {
  text: string
  link: string | ((payload: PageData) => string)
  activeMatch?: string
  target?: string
  rel?: string
  noIcon?: boolean
}

interface NavItemWithChildren {
  text?: string
  items: (NavItemChildren | NavItemWithLink)[]
  activeMatch?: string
}

sidebar

sidebar · Sidebar

Sidebar navigation configuration. Can be a simple array or multi-sidebar object.

Simple Sidebar

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/intro' },
          { text: 'Getting Started', link: '/getting-started' }
        ]
      },
      {
        text: 'Reference',
        items: [
          { text: 'API', link: '/api' },
          { text: 'Config', link: '/config' }
        ]
      }
    ]
  }
})

Multi-Sidebar

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Introduction', link: '/guide/intro' },
            { text: 'Installation', link: '/guide/install' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'Methods', link: '/api/methods' },
            { text: 'Types', link: '/api/types' }
          ]
        }
      ]
    }
  }
})

Collapsible Groups

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        collapsed: false, // Expanded by default
        items: [
          { text: 'Introduction', link: '/intro' }
        ]
      },
      {
        text: 'Advanced',
        collapsed: true, // Collapsed by default
        items: [
          { text: 'SSR', link: '/ssr' }
        ]
      }
    ]
  }
})

With Base Path

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': {
        base: '/guide/',
        items: [
          {
            text: 'Guide',
            items: [
              { text: 'Introduction', link: 'intro' }, // Becomes /guide/intro
              { text: 'Install', link: 'install' } // Becomes /guide/install
            ]
          }
        ]
      }
    }
  }
})

type Sidebar = SidebarItem[] | SidebarMulti

interface SidebarMulti {
  [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string }
}

interface SidebarItem {
  text?: string
  link?: string
  items?: SidebarItem[]
  collapsed?: boolean
  base?: string
  docFooterText?: string
  rel?: string
  target?: string
}

Social Links

socialLinks

socialLinks · SocialLink[]

Social media links displayed at the end of the nav bar.

Built-in Icons

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: 'facebook', link: 'https://facebook.com/...' },
      { icon: 'instagram', link: 'https://instagram.com/...' },
      { icon: 'linkedin', link: 'https://linkedin.com/...' },
      { icon: 'slack', link: 'https://slack.com/...' },
      { icon: 'youtube', link: 'https://youtube.com/...' }
    ]
  }
})

Custom SVG Icon

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: {
          svg: '<svg>...</svg>'
        },
        link: 'https://example.com',
        ariaLabel: 'Custom Platform'
      }
    ]
  }
})

interface SocialLink {
  icon: SocialLinkIcon
  link: string
  ariaLabel?: string
}

type SocialLinkIcon = string | { svg: string }

Page Layout

aside

aside · boolean | 'left' · default: "true"

Control the aside container position. Can be overridden per page via frontmatter.

export default defineConfig({
  themeConfig: {
    aside: 'left' // Render aside on the left
  }
})

// Disable aside globally
export default defineConfig({
  themeConfig: {
    aside: false
  }
})

outline

outline · Outline | number | [number, number] | 'deep' | false · default: "2"

Configure the outline (table of contents) in the aside.

Level Range

export default defineConfig({
  themeConfig: {
    outline: [2, 3] // Show h2 and h3 headings
  }
})

Deep Outline

export default defineConfig({
  themeConfig: {
    outline: 'deep' // Show all headings (2-6)
  }
})

Custom Label

export default defineConfig({
  themeConfig: {
    outline: {
      level: [2, 3],
      label: 'Table of Contents'
    }
  }
})

Disable

export default defineConfig({
  themeConfig: {
    outline: false
  }
})

interface Outline {
  level?: number | [number, number] | 'deep'
  label?: string
}

Page Features

editLink

editLink · EditLink

Configure the “Edit this page” link.

GitHub

export default defineConfig({
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
})

GitLab

export default defineConfig({
  themeConfig: {
    editLink: {
      pattern: 'https://gitlab.com/user/repo/-/edit/main/docs/:path',
      text: 'Edit this page on GitLab'
    }
  }
})

Dynamic Pattern

export default defineConfig({
  themeConfig: {
    editLink: {
      pattern: ({ filePath }) => {
        if (filePath.startsWith('packages/')) {
          return `https://github.com/user/monorepo/edit/main/${filePath}`
        }
        return `https://github.com/user/docs/edit/main/${filePath}`
      }
    }
  }
})

interface EditLink {
  pattern: string | ((payload: PageData) => string)
  text?: string
}

lastUpdated

lastUpdated · LastUpdatedOptions

Configure the last updated timestamp display.

export default defineConfig({
  lastUpdated: true, // Enable Git timestamps
  themeConfig: {
    lastUpdated: {
      text: 'Updated at',
      formatOptions: {
        dateStyle: 'full',
        timeStyle: 'medium'
      }
    }
  }
})

interface LastUpdatedOptions {
  text?: string
  formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
}

docFooter

docFooter · DocFooter

Customize prev/next page navigation labels.

export default defineConfig({
  themeConfig: {
    docFooter: {
      prev: 'Previous',
      next: 'Next'
    }
  }
})

// Disable prev/next navigation
export default defineConfig({
  themeConfig: {
    docFooter: {
      prev: false,
      next: false
    }
  }
})

interface DocFooter {
  prev?: string | boolean
  next?: string | boolean
}

Search

search

search · LocalSearchOptions | AlgoliaSearchOptions

Configure local search or Algolia DocSearch.

Local Search

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        detailedView: true,
        translations: {
          button: {
            buttonText: 'Search',
            buttonAriaLabel: 'Search docs'
          },
          modal: {
            displayDetails: 'Display detailed list',
            resetButtonTitle: 'Reset search',
            backButtonTitle: 'Close search',
            noResultsText: 'No results for',
            footer: {
              selectText: 'to select',
              selectKeyAriaLabel: 'enter',
              navigateText: 'to navigate',
              navigateUpKeyAriaLabel: 'up arrow',
              navigateDownKeyAriaLabel: 'down arrow',
              closeText: 'to close',
              closeKeyAriaLabel: 'escape'
            }
          }
        }
      }
    }
  }
})

Algolia

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        placeholder: 'Search docs',
        translations: {
          button: {
            buttonText: 'Search'
          }
        }
      }
    }
  }
})

Multi-locale

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          zh: {
            translations: {
              button: {
                buttonText: '搜索',
                buttonAriaLabel: '搜索文档'
              }
            }
          },
          es: {
            translations: {
              button: {
                buttonText: 'Buscar',
                buttonAriaLabel: 'Buscar documentos'
              }
            }
          }
        }
      }
    }
  }
})

Footer

footer

footer · Footer

Configure the page footer.

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

interface Footer {
  message?: string
  copyright?: string
}

Ads & Monetization

carbonAds

carbonAds · CarbonAdsOptions

Configure Carbon Ads integration.

export default defineConfig({
  themeConfig: {
    carbonAds: {
      code: 'your-carbon-code',
      placement: 'your-carbon-placement'
    }
  }
})

interface CarbonAdsOptions {
  code: string
  placement: string
}

Internationalization

i18nRouting

i18nRouting · boolean · default: "true"

Control locale-based URL routing behavior.

export default defineConfig({
  themeConfig: {
    i18nRouting: false // Disable automatic locale routing
  }
})

Accessibility Labels

darkModeSwitchLabel

darkModeSwitchLabel · string · default: "Appearance"

Aria label for the appearance switch in mobile view.

lightModeSwitchTitle

lightModeSwitchTitle · string · default: "Switch to light theme"

Title for the light mode switch.

darkModeSwitchTitle

darkModeSwitchTitle · string · default: "Switch to dark theme"

Title for the dark mode switch.

sidebarMenuLabel

sidebarMenuLabel · string · default: "Menu"

Aria label for the sidebar menu in mobile view.

returnToTopLabel

returnToTopLabel · string · default: "Return to top"

Aria label for the return to top button.

langMenuLabel

langMenuLabel · string · default: "Change language"

Aria label for the language menu button.

skipToContentLabel

skipToContentLabel · string · default: "Skip to content"

Label for the skip to content link.

export default defineConfig({
  themeConfig: {
    darkModeSwitchLabel: 'Theme',
    lightModeSwitchTitle: 'Switch to light',
    darkModeSwitchTitle: 'Switch to dark',
    sidebarMenuLabel: 'Navigation',
    returnToTopLabel: 'Back to top',
    langMenuLabel: 'Languages',
    skipToContentLabel: 'Skip navigation'
  }
})

404 Page

notFound

notFound · NotFoundOptions

Customize the 404 page.

export default defineConfig({
  themeConfig: {
    notFound: {
      title: 'PAGE NOT FOUND',
      quote: 'The page you are looking for does not exist.',
      linkLabel: 'go to home',
      linkText: 'Take me home',
      code: '404'
    }
  }
})

interface NotFoundOptions {
  title?: string
  quote?: string
  link?: string
  linkLabel?: string
  linkText?: string
  code?: string
}

External Link Icon

externalLinkIcon

externalLinkIcon · boolean · default: "false"

Show external link icon in Markdown links.

export default defineConfig({
  themeConfig: {
    externalLinkIcon: true
  }
})

Complete Example

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // Branding
    logo: { light: '/logo-light.svg', dark: '/logo-dark.svg' },
    siteTitle: 'My Docs',
    
    // Navigation
    nav: [
      { text: 'Guide', link: '/guide/' },
      {
        text: 'Reference',
        items: [
          { text: 'API', link: '/api/' },
          { text: 'Config', link: '/config/' }
        ]
      }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: 'Introduction',
          items: [
            { text: 'What is it?', link: '/guide/what-is-it' },
            { text: 'Getting Started', link: '/quickstart' }
          ]
        }
      ]
    },
    
    // Social
    socialLinks: [
      { icon: 'github', link: 'https://github.com/...' },
      { icon: 'twitter', link: 'https://twitter.com/...' }
    ],
    
    // Page features
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: 'Edit this page'
    },
    
    lastUpdated: {
      text: 'Last updated',
      formatOptions: {
        dateStyle: 'short',
        timeStyle: 'short'
      }
    },
    
    // Search
    search: {
      provider: 'local'
    },
    
    // Footer
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2024-present'
    }
  }
})

Next Steps

Site Configuration

Configure global site settings

Extending Default Theme

Customize with CSS, components, and layout slots