Config

Reference of default theme config, which can be set via themeConfig.

Basic Config

locales

Type: { [path: string]: Partial<DefaultThemeLocaleData> }
Default: {}
Details:
Specify locales for i18n support.
All the options inside the Locale Config section can be used in locales.
This option will only take effect in default theme, so don't confuse with locales in Site Config.
Also see:
- Guide > I18n

Locale Config

Config of this section can be used as normal config, and can also be used in the locales option.

home

Type: string
Default: /
Details:
Specify the path of the homepage.
This will be used for:
- the logo link of the navbar
- the back to home link of the 404 page

Type: false | (NavbarItem | NavbarGroup | string)[]
Default: []
Details:
Configuration of navbar.
Set to false to disable navbar.
To configure the navbar items, you can set it to a navbar array, each item of which could be a NavbarItem object, a NavbarGroup object, or a string:
- A NavbarItem object should have a text field and a link field, could have an optional activeMatch field.
- A NavbarGroup object should have a text field and a children field. The children field should be a navbar array, too.
- A string should be the path to the target page file. It will be converted to a NavbarItem object, using the page title as text, and the page route path as link.
Example 1:

module.exports = {
  themeConfig: {
    navbar: [
      // NavbarItem
      {
        text: 'Foo',
        link: '/foo/',
      },
      // NavbarGroup
      {
        text: 'Group',
        children: ['/group/foo.md', '/group/bar.md'],
      },
      // string - page file path
      '/bar/README.md',
    ],
  },
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Example 2:

module.exports = {
  themeConfig: {
    navbar: [
      // nested group - max depth is 2
      {
        text: 'Group',
        children: [
          {
            text: 'SubGroup',
            children: ['/group/sub/foo.md', '/group/sub/bar.md'],
          },
        ],
      },
      // control when should the item be active
      {
        text: 'Group 2',
        children: [
          {
            text: 'Always active',
            link: '/',
            // this item will always be active
            activeMatch: '/',
          },
          {
            text: 'Active on /foo/',
            link: '/not-foo/',
            // this item will be active when current route path starts with /foo/
            // regular expression is supported
            activeMatch: '^/foo/',
          },
        ],
      },
    ],
  },
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

logo

Type: string
Details:
Specify the url of logo image.
The logo image will be displayed at the left end of the navbar.
Example:

module.exports = {
  themeConfig: {
    // public file path
    logo: '/hero.png',
    // url
    logo: 'https://vuejs.org/images/logo.png',
  },
}

1
2
3
4
5
6
7
8

Also see:
- Guide > Assets > Public Files

darkMode

Type: boolean
Default: true
Details:
Enable dark mode switching or not.
If set to true, a button to switch dark mode will be displayed in the navbar, and the initial mode will be automatically set according to prefers-color-schemeopen in new window.

repo

Type: string
Details:
Specify the repository url of your project.
This will be used as the link of the repository link, which will be displayed as the last item of the navbar.

module.exports = {
  themeConfig: {
    // If you set it in the form of `organization/repository`
    // we will take it as a GitHub repo
    repo: 'vuejs/vuepress',
    // You can also set it to a URL directly
    repo: 'https://gitlab.com/foo/bar',
  },
}

1
2
3
4
5
6
7
8
9

repoLabel

Type: string
Details:
Specify the repository label of your project.
This will be used as the text of the repository link, which will be displayed as the last item of the navbar.
If you don't set this option explicitly, it will be automatically inferred from the repo option.

selectLanguageText

Type: string
Details:
Specify the text of the select language menu.
The select language menu will appear next to the repository button in the navbar when you set multiple locales in your site config.

selectLanguageAriaLabel

Type: string
Details:
Specify the aria-label attribute of the select language menu.
This is mainly for a11y purpose.

selectLanguageName

Type: string
Details:
Specify the name of the language of a locale.
This option will only take effect inside the locales of your theme config. It will be used as the language name of the locale, which will be displayed in the select language menu.
Example:

module.exports = {
  locales: {
    '/': {
      lang: 'en-US',
    },
    '/zh/': {
      lang: 'zh-CN',
    },
  },
  themeConfig: {
    locales: {
      '/': {
        selectLanguageName: 'English',
      },
      '/zh/': {
        selectLanguageName: '简体中文',
      },
    },
  },
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Type: false | 'auto' | SidebarConfigArray | SidebarConfigObject
Default: 'auto'
Details:
Configuration of sidebar.
You can override this global option via sidebar frontmatter in your pages.
Set to false to disable sidebar.
If you set it to 'auto', the sidebar will be automatically generated from the page headers.
To configure the sidebar items manually, you can set this option to a sidebar array, each item of which could be a SidebarItem object or a string:
- A SidebarItem object should have a text field, could have an optional link field and an optional children field. The children field should be a sidebar array.
- A string should be the path to the target page file. It will be converted to a SidebarItem object, whose text is the page title, link is the page route path, and children is automatically generated from the page headers.
If you want to set different sidebar for different sub paths, you can set this option to a sidebar object:
- The key should be the path prefix.
- The value should be a sidebar array.
Example 1:

module.exports = {
  themeConfig: {
    // sidebar array
    // all pages will use the same sidebar
    sidebar: [
      // SidebarItem
      {
        text: 'Foo',
        link: '/foo/',
        children: [
          // SidebarItem
          {
            text: 'github',
            link: 'https://github.com',
            children: [],
          },
          // string - page file path
          '/foo/bar.md',
        ],
      },
      // string - page file path
      '/bar/README.md',
    ],
  },
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Example 2:

module.exports = {
  themeConfig: {
    // sidebar object
    // pages under different sub paths will use different sidebar
    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          children: ['/guide/README.md', '/guide/getting-started.md'],
        },
      ],
      '/reference/': [
        {
          text: 'Reference',
          children: ['/reference/cli.md', '/reference/config.md'],
        },
      ],
    },
  },
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

sidebarDepth

Type: number
Default: 2
Details:
Set the maximum depth of the sidebar children which are automatically generated from the page headers.
- Set to 0 to disable all levels of headers.
- Set to 1 to include <h2> headers.
- Set to 2 to include <h2> and <h3> headers.
- ...
The max value depends on which levels of headers you have extracted via markdown.extractHeaders.level.
The default value of markdown.extractHeaders.level is [2, 3], so the default max value of sidebarDepth is 2.
You can override this global option via sidebarDepth frontmatter in your pages.

editLink

Type: boolean
Default: true
Details:
Enable the edit this page link or not.
You can override this global option via editLink frontmatter in your pages.

editLinkText

Type: string
Default: 'Edit this page'
Details:
Specify the text of the edit this page link.

editLinkPattern

Type: string
Details:
Specify the pattern of the edit this page link.
This will be used for generating the edit this page link.
If you don't set this option, the pattern will be inferred from the docsRepo option. But if your documentation repository is not hosted on a common platform, for example, GitHub, GitLab, Bitbucket, Gitee, etc., you have to set this option explicitly to make the edit this page link work.
Usage:
Pattern Description
:repo The docs repo url, i.e. docsRepo
:branch The docs repo branch, i.e. docsBranch
:path The path of the page source file, i.e. docsDir joins the relative path of the page file
Example:

Pattern	Description
`:repo`	The docs repo url, i.e. docsRepo
`:branch`	The docs repo branch, i.e. docsBranch
`:path`	The path of the page source file, i.e. docsDir joins the relative path of the page file

module.exports = {
  themeConfig: {
    docsRepo: 'https://gitlab.com/owner/name',
    docsBranch: 'master',
    docsDir: 'docs',
    editLinkPattern: ':repo/-/edit/:branch/:path',
  },
}

1
2
3
4
5
6
7
8

The generated link will look like 'https://gitlab.com/owner/name/-/edit/master/docs/path/to/file.md'.

docsRepo

Type: string
Details:
Specify the repository url of your documentation source files.
This will be used for generating the edit this page link.
If you don't set this option, it will use the repo option by default. But if your documentation source files are in a different repository, you will need to set this option.

docsBranch

Type: string
Default: 'main'
Details:
Specify the repository branch of your documentation source files.
This will be used for generating the edit this page link.

docsDir

Type: string
Default: ''
Details:
Specify the directory of your documentation source files in the repository.
This will be used for generating the edit this page link.

lastUpdated

Type: boolean
Default: true
Details:
Enable the last updated timestamp or not.
You can override this global option via lastUpdated frontmatter in your pages.
Notice that if you set themeConfig.lastUpdated to false, this feature will be disabled totally and could not be enabled in locales nor page frontmatter.

lastUpdatedText

Type: string
Default: 'Last Updated'
Details:
Specify the text of the last updated timestamp label.

contributors

Type: boolean
Default: true
Details:
Enable the contributors list or not.
You can override this global option via contributors frontmatter in your pages.
Notice that if you set themeConfig.contributors to false, this feature will be disabled totally and could not be enabled in locales nor page frontmatter.

contributorsText

Type: string
Default: 'Contributors'
Details:
Specify the text of the contributors list label.

tip

Type: string
Default: 'TIP'
Details:
Specify the default title of the tip custom containers.

warning

Type: string
Default: 'WARNING'
Details:
Specify the default title of the warning custom containers.

danger

Type: string
Default: 'DANGER'
Details:
Specify the default title of the danger custom containers.

notFound

Type: string[]
Default: ['Not Found']
Details:
Specify the messages of the 404 page.
The message will be randomly picked from the array when users enter the 404 page.

backToHome

Type: string
Default: 'Back to home'
Details:
Specify the text of the back to home link in the 404 page.

openInNewWindow

Type: string
Default: 'open in new window'
Details:
Specify the sr-only text of the OutboundLink.
This is mainly for a11y purpose.

toggleDarkMode

Type: string
Default: 'toggle dark mode'
Details:
Title text for dark mode toggle button.
This is mainly for a11y purpose.

Plugins Config

themePlugins

Details:
Configure the plugins that used by default theme.
Default theme is using some plugins by default. You can disable a plugin if you really do not want to use it. Make sure you understand what the plugin is for before disabling it.

themePlugins.activeHeaderLinks

Type: boolean
Default: true
Details:
Enable @vuepress/plugin-active-header-links or not.

themePlugins.backToTop

Type: boolean
Default: true
Details:
Enable @vuepress/plugin-back-to-top or not.

themePlugins.container

Type: Record<ContainerType, boolean>
Details:
Enable custom containers that powered by @vuepress/plugin-container or not.
ContainerType type is:
- tip
- warning
- danger
- details
- codeGroup
- codeGroupItem
Also see:
- Default Theme > Markdown > Custom Containers

themePlugins.git

Type: boolean
Default: true
Details:
Enable @vuepress/plugin-git or not.

themePlugins.mediumZoom

Type: boolean
Default: true
Details:
Enable @vuepress/plugin-medium-zoom or not.

themePlugins.nprogress

Type: boolean
Default: true
Details:
Enable @vuepress/plugin-nprogress or not.

# Config

# Basic Config

# locales

# Locale Config

# home

# navbar

# logo

# darkMode

# repo

# repoLabel

# selectLanguageText

# selectLanguageAriaLabel

# selectLanguageName

# sidebar

# sidebarDepth

# editLink

# editLinkText

# editLinkPattern

# docsRepo

# docsBranch

# docsDir

# lastUpdated

# lastUpdatedText

# contributors

# contributorsText

# tip

# warning

# danger

# notFound

# backToHome

# openInNewWindow

# toggleDarkMode

# Plugins Config

# themePlugins

# themePlugins.activeHeaderLinks

# themePlugins.backToTop

# themePlugins.container

# themePlugins.git

# themePlugins.mediumZoom

# themePlugins.nprogress