Sidebar

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

Each item of the array will be rendered as a sidebar item.

You can omit the .md extension, and paths ending with / are inferred as /README.md.

Icon support is enabled in the sidebar by default, and the icon of the page will be displayed before the link in the sidebar (by reading icon field in frontmatter). It can be disabled by setting sidebarIcon to false in themeConfig.

The text for the link is automatically inferred (title field in frontmatter, then first header in the page). To explicitly specify the link text, use an array in form of [link, text].

Demo

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(the max value) is 2, which extracts both h2 and h3 headers. Setting it to 0 disables the header links.

A page can also override this value via frontmatter:

---
sidebarDepth: 2
---

Displaying Header Links of All Pages

The sidebar only displays links for headers in the current active page. You can display all header links for every page with themeConfig.displayAllHeaders: true:

Active Header Links

By default, the nested header links and the hash in the URL are updated as the user scrolls to view the different sections of the page. This behavior can be disabled with the following theme config:

Sidebar Groups

You can divide the sidebar into multiple groups by using Objects. By default, each group will be rendered into a menu that can be opened and collapsed. The menu item is each group link set by children in the group.

You can use prefix field to add a default path prefix to each link in the group, and icon field to add an icon to the group text.

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

A sidebar group config also supports sidebarDepth field to override the default sidebar depth (2).

Demo

You can also nest Sidebar grouping:

You may want to use it with prefix to restore the structure of the document easily.

For example, suppose you have a following directory structure:

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

Then you can use the following config:

Note

Please pay special attention to the addition of / when configuring the sidebar. For performance considerations, we will assume that the user has correctly configured the sidebar, so we won’t perform any resolveing and verification on the path (such as traversing pages for comparison verification), but directly splicing and generating it.

Please pay attention to whether your configuration can be spliced into the correct path.

For example, bar/foo/ is expecting, while bar lacks a trailing / and foo isn’t with a prefix / resulting in barfoo/, or both are configured and an incorrect bar//foo is generated. They will cause parsing errors so the item won’t be rendered.

Tips

For the above reason, we will print any broken sidebar links in the console where the corresponding page cannot be found. This means that your misconfiguration can be easily tracked and corrected.

Multiple Sidebars

To display different sidebars for different page groups, set an object for the sidebar in the format of path: config.

For example, if you have the following structure:

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

You can define your sidebar for each section using below configuration:

Note

You need to pay special attention to the order of object key declaration. Generally speaking, you should put the more precise path first, because VuePress will traverse the key names of the sidebar configuration to find the matching configuration. Once a key name is successfully matched with the current path, it will display the corresponding sidebar configuration.

In this case, the fallback sidebar must be defined last for this reason.

Auto Sidebar for Single Pages

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

---
sidebar: auto
---

You can also enable it in all pages by using config:

Disabling the Sidebar

You can disable the sidebar on a specific page with YAML front matter:

---
sidebar: false
---

Muti language support

In multi-language (opens new window) mode, you can also apply it to a specific locale:

Blogger Information

If you have configured blog related options, you can configure themeConfig.blog.sidebarDisplay to decide whether to display the blogger’s name, avatar, and the number of articles and tags in the sidebar.

You can set 'mobile' to display only in mobile view, or set always to keep it displayed in the sidebar.

sidebarConfig

We provide a sidebarConfig Helper function. You can import it from vuepress-theme-hope and wrap your navigation bar configuration to let the editor provide auto-completion and help you verify the sidebar configuration.

Tips

When you are spliting VuePress configuration into multiple parts, you can use this helper function to keep automatic completion and verification.

Demo

Configuration of this documentation