> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vuejs/vitepress/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts theme={null}
export default {
  themeConfig: {
    logo: '/logo.svg',
    nav: [...],
    sidebar: {...}
  }
}
```

<Note>These options only apply to the **default theme**. Custom themes may have different configurations.</Note>

## Branding

### logo

<ParamField path="logo" type="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.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  type ThemeableImage =
    | string
    | { src: string; alt?: string; [prop: string]: any }
    | { light: string; dark: string; alt?: string; [prop: string]: any }
  ```
</Expandable>

<CodeGroup>
  ```ts Simple theme={null}
  export default {
    themeConfig: {
      logo: '/logo.svg'
    }
  }
  ```

  ```ts Light/Dark Mode theme={null}
  export default {
    themeConfig: {
      logo: {
        light: '/logo-light.svg',
        dark: '/logo-dark.svg',
        alt: 'My Site Logo'
      }
    }
  }
  ```
</CodeGroup>

### logoLink

<ParamField path="logoLink" type="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.
</ParamField>

```ts theme={null}
export default {
  themeConfig: {
    logoLink: 'https://example.com'
  }
}
```

### siteTitle

<ParamField path="siteTitle" type="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.
</ParamField>

```ts theme={null}
export default {
  themeConfig: {
    siteTitle: 'My Custom Title'
  }
}
```

## Navigation

### nav

<ParamField path="nav" type="NavItem[]">
  Configuration for the navigation menu in the navbar.
</ParamField>

<Expandable title="Type Definitions">
  ```ts theme={null}
  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
  }
  ```
</Expandable>

<Tabs>
  <Tab title="Basic">
    ```ts theme={null}
    export default {
      themeConfig: {
        nav: [
          { text: 'Guide', link: '/guide' },
          { text: 'API', link: '/api' },
          { text: 'Blog', link: '/blog' }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Dropdown">
    ```ts theme={null}
    export default {
      themeConfig: {
        nav: [
          { text: 'Home', link: '/' },
          {
            text: 'Resources',
            items: [
              { text: 'Documentation', link: '/docs' },
              { text: 'Examples', link: '/examples' },
              { text: 'Tutorials', link: '/tutorials' }
            ]
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Grouped Dropdown">
    ```ts theme={null}
    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' }
                ]
              }
            ]
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### sidebar

<ParamField path="sidebar" type="Sidebar">
  Configuration for the sidebar menu. Can be a simple array or an object with multiple sidebars for different sections.
</ParamField>

<Expandable title="Type Definitions">
  ```ts theme={null}
  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
  }
  ```
</Expandable>

<Tabs>
  <Tab title="Simple">
    ```ts theme={null}
    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' }
            ]
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Multiple Sidebars">
    ```ts theme={null}
    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' }
              ]
            }
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Collapsible">
    ```ts theme={null}
    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' }
            ]
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

## Content Layout

### aside

<ParamField path="aside" type="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.
</ParamField>

```ts theme={null}
export default {
  themeConfig: {
    aside: 'left'
  }
}
```

### outline

<ParamField path="outline" type="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).
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  interface Outline {
    level?: number | [number, number] | 'deep'  // 'deep' = [2, 6]
    label?: string  // Default: 'On this page'
  }
  ```
</Expandable>

<CodeGroup>
  ```ts Single Level theme={null}
  export default {
    themeConfig: {
      outline: 2  // Only <h2> headings
    }
  }
  ```

  ```ts Range theme={null}
  export default {
    themeConfig: {
      outline: [2, 4]  // <h2> to <h4>
    }
  }
  ```

  ```ts Deep with Custom Label theme={null}
  export default {
    themeConfig: {
      outline: {
        level: 'deep',  // All headings from <h2> to <h6>
        label: 'Table of Contents'
      }
    }
  }
  ```

  ```ts Disabled theme={null}
  export default {
    themeConfig: {
      outline: false
    }
  }
  ```
</CodeGroup>

### outlineTitle <Badge type="warning" text="deprecated" />

<ParamField path="outlineTitle" type="string" default="On this page">
  **Deprecated**: Use `outline.label` instead.

  Custom title for the outline in the aside component.
</ParamField>

## Social & External Links

### socialLinks

<ParamField path="socialLinks" type="SocialLink[]">
  Social account links with icons displayed at the end of the nav bar. Supports any icon from [simple-icons](https://simpleicons.org/) or custom SVG.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  interface SocialLink {
    icon: SocialLinkIcon
    link: string
    ariaLabel?: string
  }

  type SocialLinkIcon = string | { svg: string }
  ```
</Expandable>

<CodeGroup>
  ```ts Built-in Icons theme={null}
  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' }
      ]
    }
  }
  ```

  ```ts Custom SVG Icon theme={null}
  export default {
    themeConfig: {
      socialLinks: [
        {
          icon: {
            svg: '<svg role="img" viewBox="0 0 24 24"><path d="M12..."/></svg>'
          },
          link: 'https://example.com',
          ariaLabel: 'Example Site'
        }
      ]
    }
  }
  ```
</CodeGroup>

### externalLinkIcon

<ParamField path="externalLinkIcon" type="boolean" default="false">
  Show an external link icon next to external links in markdown content.
</ParamField>

```ts theme={null}
export default {
  themeConfig: {
    externalLinkIcon: true
  }
}
```

## Footer

### footer

<ParamField path="footer" type="Footer">
  Footer configuration. Only displayed when the page doesn't contain a sidebar.

  Can be overridden per page via frontmatter.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  interface Footer {
    message?: string
    copyright?: string
  }
  ```
</Expandable>

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

### docFooter

<ParamField path="docFooter" type="DocFooter">
  Customize the text appearing in the previous/next page navigation. Can disable prev/next links by setting to `false`.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  interface DocFooter {
    prev?: string | boolean  // Default: 'Previous page'
    next?: string | boolean  // Default: 'Next page'
  }
  ```
</Expandable>

<CodeGroup>
  ```ts Custom Labels theme={null}
  export default {
    themeConfig: {
      docFooter: {
        prev: 'Previous',
        next: 'Next'
      }
    }
  }
  ```

  ```ts Disable theme={null}
  export default {
    themeConfig: {
      docFooter: {
        prev: false,
        next: false
      }
    }
  }
  ```
</CodeGroup>

## Edit Link

### editLink

<ParamField path="editLink" type="EditLink">
  Display a link to edit the page on Git management services (GitHub, GitLab, etc.).

  Can be overridden per page via frontmatter.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  interface EditLink {
    pattern: string | ((payload: PageData) => string)
    text?: string  // Default: 'Edit this page'
  }
  ```
</Expandable>

<CodeGroup>
  ```ts GitHub theme={null}
  export default {
    themeConfig: {
      editLink: {
        pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
        text: 'Edit this page on GitHub'
      }
    }
  }
  ```

  ```ts GitLab theme={null}
  export default {
    themeConfig: {
      editLink: {
        pattern: 'https://gitlab.com/user/repo/-/edit/main/docs/:path'
      }
    }
  }
  ```

  ```ts Dynamic theme={null}
  export default {
    themeConfig: {
      editLink: {
        pattern: ({ filePath }) => {
          if (filePath.startsWith('packages/')) {
            return `https://github.com/user/repo/edit/main/${filePath}`
          }
          return `https://github.com/user/docs/edit/main/${filePath}`
        }
      }
    }
  }
  ```
</CodeGroup>

## Last Updated

### lastUpdated

<ParamField path="lastUpdated" type="LastUpdatedOptions">
  Customize the last updated text and date format.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  interface LastUpdatedOptions {
    text?: string  // Default: 'Last updated'
    formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
  }
  ```
</Expandable>

```ts theme={null}
export default {
  themeConfig: {
    lastUpdated: {
      text: 'Updated at',
      formatOptions: {
        dateStyle: 'full',
        timeStyle: 'medium'
      }
    }
  }
}
```

### lastUpdatedText <Badge type="warning" text="deprecated" />

<ParamField path="lastUpdatedText" type="string" default="Last updated">
  **Deprecated**: Use `lastUpdated.text` instead.

  Custom text for the last updated label.
</ParamField>

## Search

### search

<ParamField path="search" type="LocalSearchOptions | AlgoliaSearchOptions">
  Search configuration. Supports local search or Algolia DocSearch.
</ParamField>

<Tabs>
  <Tab title="Local Search">
    ```ts theme={null}
    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'
                }
              }
            }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Algolia">
    ```ts theme={null}
    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'
                  }
                }
              }
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Expandable title="LocalSearchOptions">
  ```ts theme={null}
  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']
    }
  }
  ```
</Expandable>

## Advertising

### carbonAds

<ParamField path="carbonAds" type="CarbonAdsOptions">
  Display Carbon Ads on your site.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  interface CarbonAdsOptions {
    code: string
    placement: string
  }
  ```
</Expandable>

```ts theme={null}
export default {
  themeConfig: {
    carbonAds: {
      code: 'your-carbon-code',
      placement: 'your-carbon-placement'
    }
  }
}
```

## Internationalization

### i18nRouting

<ParamField path="i18nRouting" type="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.
</ParamField>

```ts theme={null}
export default {
  themeConfig: {
    i18nRouting: false
  }
}
```

### langMenuLabel

<ParamField path="langMenuLabel" type="string" default="Change language">
  Custom `aria-label` for the language menu button.
</ParamField>

```ts theme={null}
export default {
  themeConfig: {
    langMenuLabel: 'Select language'
  }
}
```

## Accessibility Labels

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

### darkModeSwitchLabel

<ParamField path="darkModeSwitchLabel" type="string" default="Appearance">
  Label for the dark mode switch (mobile view only).
</ParamField>

### lightModeSwitchTitle

<ParamField path="lightModeSwitchTitle" type="string" default="Switch to light theme">
  Hover title for the light mode switch.
</ParamField>

### darkModeSwitchTitle

<ParamField path="darkModeSwitchTitle" type="string" default="Switch to dark theme">
  Hover title for the dark mode switch.
</ParamField>

### sidebarMenuLabel

<ParamField path="sidebarMenuLabel" type="string" default="Menu">
  Label for the sidebar menu (mobile view only).
</ParamField>

### returnToTopLabel

<ParamField path="returnToTopLabel" type="string" default="Return to top">
  Label for the return to top button (mobile view only).
</ParamField>

### skipToContentLabel

<ParamField path="skipToContentLabel" type="string" default="Skip to content">
  Label for the skip to content link (keyboard navigation).
</ParamField>

## 404 Page

### notFound

<ParamField path="notFound" type="NotFoundOptions">
  Customize the 404 page text and behavior.
</ParamField>

<Expandable title="Type Definition">
  ```ts theme={null}
  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'
  }
  ```
</Expandable>

```ts theme={null}
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'
    }
  }
}
```