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

ThemeableImage

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

Simple Logo
With Alt Text
Light/Dark Mode

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

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

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

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

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

nav

NavItem[]

Navigation menu items displayed in the header.

Simple Links
Dropdown Menu
Nested Dropdown
Active State
Dynamic Links

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

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

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

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

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 navigation configuration. Can be a simple array or multi-sidebar object.

Simple Sidebar
Multi-Sidebar
Collapsible Groups
With Base Path

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

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

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

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
}

socialLinks

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

Built-in Icons
Custom SVG Icon

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

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

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 | number | [number, number] | 'deep' | false

default:"2"

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

Level Range
Deep Outline
Custom Label
Disable

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

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

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

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

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

Page Features

editLink

EditLink

Configure the “Edit this page” link.

GitHub
GitLab
Dynamic Pattern

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

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

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

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

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

LocalSearchOptions | AlgoliaSearchOptions

Configure local search or Algolia DocSearch.

Local Search
Algolia
Multi-locale

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

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

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

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

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

boolean

default:"true"

Control locale-based URL routing behavior.

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

Accessibility Labels

darkModeSwitchLabel

string

default:"Appearance"

Aria label for the appearance switch in mobile view.

lightModeSwitchTitle

string

default:"Switch to light theme"

Title for the light mode switch.

darkModeSwitchTitle

string

default:"Switch to dark theme"

Title for the dark mode switch.

sidebarMenuLabel

Aria label for the sidebar menu in mobile view.

returnToTopLabel

string

default:"Return to top"

Aria label for the return to top button.

langMenuLabel

Aria label for the language menu button.

skipToContentLabel

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

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

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

Getting Started

Core Concepts

Customization

Advanced

​Default Theme Configuration

​Site Branding

​logo

​logoLink

​siteTitle

​Navigation

​nav

​sidebar

​Social Links

​socialLinks

​Page Layout

​aside

​outline

​Page Features

​editLink

​lastUpdated

​docFooter

​Search

​search

​Footer

​footer

​Ads & Monetization

​carbonAds

​Internationalization

​i18nRouting

​Accessibility Labels

​darkModeSwitchLabel

​lightModeSwitchTitle

​darkModeSwitchTitle

​sidebarMenuLabel

​returnToTopLabel

​langMenuLabel

​skipToContentLabel

​404 Page

​notFound

​External Link Icon

​externalLinkIcon

​Complete Example

​Next Steps

Site Configuration

Extending Default Theme

Build docs developers (and LLMs) love

Default Theme Configuration

Site Branding

logo

logoLink

siteTitle

Navigation

nav

sidebar

Social Links

socialLinks

Page Layout

aside

outline

Page Features

editLink

lastUpdated

docFooter

Search

search

Footer

footer

Ads & Monetization

carbonAds

Internationalization

i18nRouting

Accessibility Labels

darkModeSwitchLabel

lightModeSwitchTitle

darkModeSwitchTitle

sidebarMenuLabel

returnToTopLabel

langMenuLabel

skipToContentLabel

404 Page

notFound

External Link Icon

externalLinkIcon

Complete Example

Next Steps