Sidebar

Mr.Hope ... Layout
  • Sidebar
  • Layout
About 3 min

# 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"]],
  },
};
1
2
3
4
5
6

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 front matter). To explicitly specify the link text, use an array in form of [link, text].

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

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 Front matter:

---
sidebarDepth: 2
---
1
2
3

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:

module.exports = {
  themeConfig: {
    displayAllHeaders: true, // Default: false
  },
};
1
2
3
4
5

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:

module.exports = {
  themeConfig: {
    activeHeaderLinks: false, // Default: true
  },
};
1
2
3
4
5

You can divide sidebar links into mutiple groups by using objects. You can use prefix to add a default path prefix to each link in the group, and icon to add an icon to the group text.

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: "Group 1", // required
        path: "/foo/", // optional, which should be a absolute path.
        collapsable: false, // optional, defaults to true
        sidebarDepth: 2, // optional, defaults to 2
        children: ["/"],
      },
      {
        title: "Group 2",
        children: [
          /* ... */
        ],
      },
    ],
  },
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

# Multiple Sidebars

To display different sidebars for different sections of content, first organize your pages into directories for each desired section:

.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│   ├─ README.md
│   ├─ one.md
│   └─ two.md
└─ bar/
    ├─ README.md
    ├─ three.md
    └─ four.md
1
2
3
4
5
6
7
8
9
10
11
12

Then, update your configuration to define your sidebar for each section.

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      "/foo/": [
        "" /* /foo/ */,
        "one" /* /foo/one.html */,
        "two" /* /foo/two.html */,
      ],

      "/bar/": [
        "" /* /bar/ */,
        "three" /* /bar/three.html */,
        "four" /* /bar/four.html */,
      ],

      // fallback
      "/": [
        "" /* / */,
        "contact" /* /contact.html */,
        "about" /* /about.html */,
      ],
    },
  },
};
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

Note

Make sure to define the fallback configuration last, because VuePress checks each sidebar config from top to bottom.

# Auto Sidebar for Single Pages

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

---
sidebar: auto
---

1
2
3
4

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

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: "auto",
  },
};
1
2
3
4
5
6

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

// .vuepress/config.js
module.exports = {
  themeConfig: {
    "/": {
      sidebar: "auto",
    },
  },
};
1
2
3
4
5
6
7
8

# Disabling the Sidebar

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

---
sidebar: false
---

1
2
3
4

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

# Demo

Configuration of this documentation
// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      "/guide/": [
        {
          title: "Get Started",
          icon: "creative",
          collapsable: false,
          children: ["", "install"],
        },
        {
          title: "New Features",
          icon: "discover",
          prefix: "feature/",
          collapsable: false,
          children: [
            "",
            "theme",
            "page-info",
            "comment",
            "blog",
            "encrypt",
            {
              title: "Markdown enhance",
              icon: "markdown",
              prefix: "markdown/",
              collapsable: false,
              children: [
                "",
                "align",
                "sup-sub",
                "footnote",
                "mark",
                "tex",
                "flowchart",
                "presentation",
              ],
            },
            "component",
            "seo-sitemap",
            "typescript",
          ],
        },
        {
          title: "Outlook",
          icon: "layout",
          prefix: "layout/",
          collapsable: false,
          children: ["", "navbar", "sidebar", "page", "home", "blog"],
        },
      ],

      "/config/": [
        {
          title: "ThemeConfig",
          icon: "config",
          prefix: "theme/",
          collapsable: false,
          children: ["", "default", "feature", "plugin", "apperance"],
        },
        "page",
        "stylus",
        {
          title: "Plugins",
          icon: "extension",
          prefix: "plugin/",
          collapsable: false,
          children: ["", "container", "copyright"],
        },
      ],

      "/basic/": [
        {
          title: "Markdown",
          icon: "markdown",
          prefix: "markdown/",
          collapsable: false,
          children: [
            "",
            "demo",
            {
              title: "Emoji",
              icon: "emoji",
              path: "emoji/",
              prefix: "emoji/",
              collapsable: false,
              children: ["people", "nature", "object", "place", "symbol"],
            },
          ],
        },
        {
          title: "VuePress",
          icon: "vue",
          prefix: "vuepress/",
          collapsable: false,
          children: ["", "file", "plugin", "theme", "command", "case"],
        },
      ],

      "/": ["", "guide/", "config/", "basic/", "FAQ/", "demo/"],
    },
  },
};
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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104