vuepress/docs/default-theme-config

sidebar

sidebar
auto

Default Theme Config

::: tip All options listed on this page apply to the default theme only. If you are using a custom theme, the options may be different. :::

Navbar Links

You can add links to the navbar via themeConfig.nav:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
    ]
  }
}

Sidebar

To enable the sidebar, use themeConfig.sidebar. The basic configuration expects an Array of links:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/page-a',
      ['/page-b', 'Explicit link text']
    ]
  }
}

You can omit the .md extension, and paths ending with / are inferred as */README.md. The text for the link is automatically inferred (either from the first header in the page or explicit title in YAML frontmatter). If you wish to explicitly specify the link text, use an Array in form of [link, text].

Nested Header Links

The sidebar automatically displays links for headers in the current active page, nested under the link for the page itself. You can customize this behavior using themeConfig.sidebarDepth. The default depth is 1, which extracts the h2 headers. Setting it to 0 disables the header links, and the max value is 2 which extracts both h2 and h3 headers.

A page can also override this value in using YAML frontmatter:

---
sidebarDepth: 2
---

Sidebar Groups

You can divide sidebar links into multiple groups by using objects:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'Group 1',
        collapsable: false,
        children: [
          '/'
        ]
      },
      {
        title: 'Group 2',
        children: [ /* ... */ ]
      }
    ]
  }
}

Sidebar groups are collapsable by default. You can force a group to be always open with collapsable: false.

Multiple Sidebars

If you wish to display different sidebars for different group of pages, first organize your pages into directories:

.
├─ README.md
├─ foo
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ README.md
   ├─ three.md
   └─ four.md

Then, with the following sidebar config:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      // sidebar for pages under /foo/
      '/foo/': [
        '',
        'one',
        'two'
      ],
      // sidebar for pages under /bar/
      '/bar/': [
        '',
        'three',
        'four'
      ]
    }
  }
}

Auto Sidebar for Single Pages

If you wish to automatically generate a sidebar that contains only the header links for the current page, you can use YAML frontmatter on that page:

---
sidebar: auto
---

Homepage

GitHub Repo and Edit Links

Providing themeConfig.repo auto generates a GitHub link in the navbar and "Edit this page" links at the bottom of each page.

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // Assumes GitHub. Can also be a full GitLab url.
    repo: 'vuejs/vuepress',
    // if your docs are not at the root of the repo
    docsDir: 'docs',
    // optional, defaults to master
    docsBranch: 'master',
    // defaults to true, set to false to disable
    editLinks: true
  }
}

Simple CSS Override

If you wish to apply simple overrides to the styling of the default theme, you can create an .vuepress/override.styl file. This is a Stylus file but you can use normal CSS syntax as well.

There are a few color variables you can tweak:

// showing default values
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34