Theme Config Reference

Complete reference for VitePress default theme configuration options

Theme Config Reference

Theme config allows you to customize the default theme. Define theme config via the themeConfig option in your config file.

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

These options only apply to the default theme. Custom themes may have different configurations.

Branding

logo

logo · ThemeableImage

Logo file to display in the navbar, right before the site title. Accepts a path string or an object to set different logos for light/dark mode.

Show Type Definition

type ThemeableImage =
  | string
  | { src: string; alt?: string; [prop: string]: any }
  | { light: string; dark: string; alt?: string; [prop: string]: any }

Simple

export default {
  themeConfig: {
    logo: '/logo.svg'
  }
}

logoLink

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

Overrides the link of the site logo. Useful if you want the logo to link to an external site.

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

siteTitle

siteTitle · string | false

Customizes the site title in navbar. If undefined, config.title will be used. Set to false to disable the title.

Useful when your logo already contains the site title text.

export default {
  themeConfig: {
    siteTitle: 'My Custom Title'
  }
}

Navigation

nav

nav · NavItem[]

Configuration for the navigation menu in the navbar.

Show Type Definitions

type NavItem = NavItemComponent | NavItemWithLink | NavItemWithChildren

interface NavItemComponent {
  component: string
  props?: Record<string, any>
}

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

interface NavItemChildren {
  text?: string
  items: NavItemWithLink[]
}

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

Basic

export default {
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide' },
      { text: 'API', link: '/api' },
      { text: 'Blog', link: '/blog' }
    ]
  }
}

Dropdown

export default {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      {
        text: 'Resources',
        items: [
          { text: 'Documentation', link: '/docs' },
          { text: 'Examples', link: '/examples' },
          { text: 'Tutorials', link: '/tutorials' }
        ]
      }
    ]
  }
}

Grouped Dropdown

export default {
  themeConfig: {
    nav: [
      {
        text: 'Reference',
        items: [
          {
            text: 'API',
            items: [
              { text: 'Site Config', link: '/api/site-config' },
              { text: 'Theme Config', link: '/api/theme-config' }
            ]
          },
          {
            text: 'Guides',
            items: [
              { text: 'Getting Started', link: '/guide/start' },
              { text: 'Advanced', link: '/guide/advanced' }
            ]
          }
        ]
      }
    ]
  }
}

sidebar

sidebar · Sidebar

Configuration for the sidebar menu. Can be a simple array or an object with multiple sidebars for different sections.

Show Type Definitions

type Sidebar = SidebarItem[] | SidebarMulti

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

interface SidebarItem {
  text?: string
  link?: string
  items?: SidebarItem[]
  collapsed?: boolean  // true = collapsed, false = expanded, undefined = not collapsible
  base?: string        // Base path for children items
  docFooterText?: string
  rel?: string
  target?: string
}

Simple

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' }
        ]
      },
      {
        text: 'API',
        items: [
          { text: 'Site Config', link: '/api/site-config' },
          { text: 'Theme Config', link: '/api/theme-config' }
        ]
      }
    ]
  }
}

Multiple Sidebars

export default {
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Introduction', link: '/guide/intro' },
            { text: 'Getting Started', link: '/guide/start' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'Site Config', link: '/api/site-config' },
            { text: 'Theme Config', link: '/api/theme-config' }
          ]
        }
      ]
    }
  }
}

Collapsible

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Configuration',
        collapsed: false,  // Expanded by default
        items: [
          { text: 'Site Config', link: '/config/site' },
          { text: 'Theme Config', link: '/config/theme' }
        ]
      },
      {
        text: 'Advanced',
        collapsed: true,  // Collapsed by default
        items: [
          { text: 'Custom Theme', link: '/advanced/theme' },
          { text: 'Plugins', link: '/advanced/plugins' }
        ]
      }
    ]
  }
}

Content Layout

aside

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

Controls the rendering of the aside (table of contents) container.

• false: No aside
• true: Aside to the right
• 'left': Aside to the left

Can be overridden per page via frontmatter.

export default {
  themeConfig: {
    aside: 'left'
  }
}

outline

outline · Outline | Outline['level'] | false · default: "2"

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

Can be overridden per page via frontmatter (level only).

Show Type Definition

interface Outline {
  level?: number | [number, number] | 'deep'  // 'deep' = [2, 6]
  label?: string  // Default: 'On this page'
}

Single Level

export default {
  themeConfig: {
    outline: 2  // Only <h2> headings
  }
}

outlineTitle

outlineTitle · string · default: "On this page"

Deprecated: Use outline.label instead.

Custom title for the outline in the aside component.

Social & External Links

socialLinks

socialLinks · SocialLink[]

Social account links with icons displayed at the end of the nav bar. Supports any icon from simple-icons or custom SVG.

Show Type Definition

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

type SocialLinkIcon = string | { svg: string }

Built-in Icons

export default {
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: 'https://twitter.com/yourusername' },
      { icon: 'discord', link: 'https://discord.gg/yourserver' }
    ]
  }
}

externalLinkIcon

externalLinkIcon · boolean · default: "false"

Show an external link icon next to external links in markdown content.

export default {
  themeConfig: {
    externalLinkIcon: true
  }
}

Footer

footer

footer · Footer

Footer configuration. Only displayed when the page doesn’t contain a sidebar.

Can be overridden per page via frontmatter.

Show Type Definition

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

export default {
  themeConfig: {
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2019-present Evan You'
    }
  }
}

docFooter

docFooter · DocFooter

Customize the text appearing in the previous/next page navigation. Can disable prev/next links by setting to false.

Show Type Definition

interface DocFooter {
  prev?: string | boolean  // Default: 'Previous page'
  next?: string | boolean  // Default: 'Next page'
}

Custom Labels

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

Edit Link

editLink

editLink · EditLink

Display a link to edit the page on Git management services (GitHub, GitLab, etc.).

Can be overridden per page via frontmatter.

Show Type Definition

interface EditLink {
  pattern: string | ((payload: PageData) => string)
  text?: string  // Default: 'Edit this page'
}

GitHub

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

Last Updated

lastUpdated

lastUpdated · LastUpdatedOptions

Customize the last updated text and date format.

Show Type Definition

interface LastUpdatedOptions {
  text?: string  // Default: 'Last updated'
  formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
}

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

lastUpdatedText

lastUpdatedText · string · default: "Last updated"

Deprecated: Use lastUpdated.text instead.

Custom text for the last updated label.

Search

search

search · LocalSearchOptions | AlgoliaSearchOptions

Search configuration. Supports local search or Algolia DocSearch.

Local Search

export default {
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        detailedView: true,
        translations: {
          button: {
            buttonText: 'Search',
            buttonAriaLabel: 'Search'
          },
          modal: {
            noResultsText: 'No results for',
            resetButtonTitle: 'Reset search',
            footer: {
              selectText: 'to select',
              navigateText: 'to navigate',
              closeText: 'to close'
            }
          }
        }
      }
    }
  }
}

Algolia

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        locales: {
          fr: {
            placeholder: 'Rechercher',
            translations: {
              button: {
                buttonText: 'Rechercher'
              }
            }
          }
        }
      }
    }
  }
}

Show LocalSearchOptions

interface LocalSearchOptions {
  disableDetailedView?: boolean  // Deprecated: use detailedView instead
  detailedView?: boolean | 'auto'  // Default: 'auto'
  disableQueryPersistence?: boolean  // Default: false
  translations?: LocalSearchTranslations
  locales?: Record<string, Partial<Omit<LocalSearchOptions, 'locales'>>>
  miniSearch?: {
    options?: Pick<MiniSearchOptions, 'extractField' | 'tokenize' | 'processTerm'>
    searchOptions?: MiniSearchOptions['searchOptions']
  }
}

Advertising

carbonAds

carbonAds · CarbonAdsOptions

Display Carbon Ads on your site.

Show Type Definition

interface CarbonAdsOptions {
  code: string
  placement: string
}

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

Internationalization

i18nRouting

i18nRouting · boolean · default: "true"

Changing locale to say zh will change the URL from /foo (or /en/foo/) to /zh/foo. Set to false to disable this behavior.

export default {
  themeConfig: {
    i18nRouting: false
  }
}

langMenuLabel

langMenuLabel · string · default: "Change language"

Custom aria-label for the language menu button.

export default {
  themeConfig: {
    langMenuLabel: 'Select language'
  }
}

Accessibility Labels

These options are only displayed in mobile view or for screen readers.

darkModeSwitchLabel

darkModeSwitchLabel · string · default: "Appearance"

Label for the dark mode switch (mobile view only).

lightModeSwitchTitle

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

Hover title for the light mode switch.

darkModeSwitchTitle

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

Hover title for the dark mode switch.

sidebarMenuLabel

sidebarMenuLabel · string · default: "Menu"

Label for the sidebar menu (mobile view only).

returnToTopLabel

returnToTopLabel · string · default: "Return to top"

Label for the return to top button (mobile view only).

skipToContentLabel

skipToContentLabel · string · default: "Skip to content"

Label for the skip to content link (keyboard navigation).

404 Page

notFound

notFound · NotFoundOptions

Customize the 404 page text and behavior.

Show Type Definition

interface NotFoundOptions {
  title?: string          // Default: 'PAGE NOT FOUND'
  quote?: string          // Default: "But if you don't change your direction..."
  link?: string           // Default: '/'
  linkLabel?: string      // Default: 'go to home'
  linkText?: string       // Default: 'Take me home'
  code?: string           // Default: '404'
}

export default {
  themeConfig: {
    notFound: {
      title: 'Oops! Page Not Found',
      quote: 'The page you are looking for does not exist.',
      linkText: 'Go back home',
      code: '404'
    }
  }
}