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

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 }

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

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

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

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
Dropdown
Grouped Dropdown

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

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

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

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
Multiple Sidebars
Collapsible

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

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

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

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

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

outlineTitle

string

default:"On this page"

Deprecated: Use outline.label instead.Custom title for the outline in the aside component.

socialLinks

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 }

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

boolean

default:"false"

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

export default {
  themeConfig: {
    externalLinkIcon: true
  }
}

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

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

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

Edit Link

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

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

Last Updated

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

string

default:"Last updated"

Deprecated: Use lastUpdated.text instead.Custom text for the last updated label.

Search

search

LocalSearchOptions | AlgoliaSearchOptions

Search configuration. Supports local search or Algolia DocSearch.

Local Search
Algolia

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

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

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

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

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

string

default:"Appearance"

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

lightModeSwitchTitle

string

default:"Switch to light theme"

Hover title for the light mode switch.

darkModeSwitchTitle

string

default:"Switch to dark theme"

Hover title for the dark mode switch.

sidebarMenuLabel

Label for the sidebar menu (mobile view only).

returnToTopLabel

string

default:"Return to top"

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

skipToContentLabel

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

404 Page

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

Configuration

Node API

Client API

​Theme Config Reference

​Branding

​logo

​logoLink

​siteTitle

​Navigation

​nav

​sidebar

​Content Layout

​aside

​outline

​outlineTitle

​Social & External Links

​socialLinks

​externalLinkIcon

​Footer

​footer

​docFooter

​Edit Link

​editLink

​Last Updated

​lastUpdated

​lastUpdatedText

​Search

​search

​Advertising

​carbonAds

​Internationalization

​i18nRouting

​langMenuLabel

​Accessibility Labels

​darkModeSwitchLabel

​lightModeSwitchTitle

​darkModeSwitchTitle

​sidebarMenuLabel

​returnToTopLabel

​skipToContentLabel

​404 Page

​notFound

Build docs developers (and LLMs) love

Theme Config Reference

Branding

logo

logoLink

siteTitle

Navigation

nav

sidebar

Content Layout

aside

outline

outlineTitle

Social & External Links

socialLinks

externalLinkIcon

Footer

footer

docFooter

Edit Link

editLink

Last Updated

lastUpdated

lastUpdatedText

Search

search

Advertising

carbonAds

Internationalization

i18nRouting

langMenuLabel

Accessibility Labels

darkModeSwitchLabel

lightModeSwitchTitle

darkModeSwitchTitle

sidebarMenuLabel

returnToTopLabel

skipToContentLabel

404 Page

notFound