NavBar

Mr.Hope ... January 27, 2020 14:39 Layout
  • Navbar
  • Layout
About 5 min

The Navbar may contain your site title, Search Box, Navbar Links, Languages (opens new window) and Repository Link, they all depend on your configuration.

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

The basic configuration items are text navigation bar text, link navigation bar link, and icon navigation bar icon:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: "Guide", link: "/guide/", icon: "creative" },
      { text: "Config", link: "/config/", icon: "config" },
      { text: "FAQ", link: "/FAQ/", icon: "question" },
    ],
  },
};
1
2
3
4
5
6
7
8
9
10

These links can also be dropdown menus if you provide an array of items instead of a link:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: "Basic",
        icon: "info",
        items: [
          { text: "Markdown", link: "/basic/markdown/", icon: "markdown" },
          { text: "VuePress", link: "/basic/vuepress/", icon: "vue" },
        ],
      },
    ],
  },
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14

In most cases, the grouped items in the navigation bar belong to the same category and will be placed in the same subdirectory, and they have the same path prefix. To simplify the configuration, you can add the prefix field to add a prefix to each sub-link in the group:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      {
        text: "Basic",
        icon: "info",
        prefix: "/basic/",
        items: [
          { text: "Markdown", link: "markdown/", icon: "markdown" },
          { text: "VuePress", link: "vuepress/", icon: "vue" },
        ],
      },
    ],
  },
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

You can also have sub groups inside a dropdown by having nested items:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: "Project",
        icon: "info",
        items: [
          {
            text: "Built in Plugins",
            icon: "plugin",
            items: [
              /* Some items */
            ],
          },
          {
            text: "Third party Plugins",
            icon: "plugin",
            items: [
              /* Some items */
            ],
          },
        ],
      },
    ],
  },
};
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
Demo
// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      {
        text: "Project",
        icon: "info",
        items: [
          {
            text: "Changelog",
            link:
              "https://github.com/vuepress-theme-hope/vuepress-theme-hope/blob/v1/CHANGELOG.md",
          },
          {
            text: "Repo",
            link: "https://github.com/vuepress-theme-hope/vuepress-theme-hope",
          },
          {
            text: "Theme Demo",
            link: "/demo/",
          },
          {
            text: "Plugins",
            icon: "plugin",
            items: [
              {
                text: "AddThis Plugin",
                link: "https://vuepress-theme-hope.github.io/add-this/",
              },
              {
                text: "Comment Plugin",
                link: "https://vuepress-theme-hope.github.io/comment/",
              },
              {
                text: "Copy Code Plugin",
                link: "https://vuepress-theme-hope.github.io/copy-code/",
              },
              {
                text: "Feed Plugin",
                link: "https://vuepress-theme-hope.github.io/feed/",
              },
              {
                text: "Git Info Plugin",
                link: "https://vuepress-theme-hope.github.io/git/",
              },
              {
                text: "Markdown Enhance Plugin",
                link: "https://vuepress-theme-hope.github.io/md-enhance/",
              },
              {
                text: "Photo Swipe Plugin",
                link: "https://vuepress-theme-hope.github.io/photo-swipe/",
              },
              {
                text: "PWA Plugin",
                link: "https://vuepress-theme-hope.github.io/pwa/",
              },
              {
                text: "Reading Time Plugin",
                link: "https://vuepress-theme-hope.github.io/reading-time/",
              },
              {
                text: "Seo Plugin",
                link: "https://vuepress-theme-hope.github.io/seo/",
              },
              {
                text: "Sitemap Plugin",
                link: "https://vuepress-theme-hope.github.io/sitemap/",
              },
            ],
          },
        ],
      },
    ],
  },
};
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

# Disable the Navbar

To disable the navbar globally, use themeConfig.navbar:

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

You can disable the navbar for a specific page via YAML front matter:

---
navbar: false
---
1
2
3

You can use themeConfig.logo to configure the icons of the navigation bar, please fill in the absolute path.

After configuring the icon, the icon will be displayed on the navigation bar instead of the previous site name on the mobile view.

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

Tips

You can set themeConfig.darkLogo to display another logo in dark mode.

You can disable the built-in search box with themeConfig.search: false, and customize the number of suggestions will be shown with themeConfig.searchMaxSuggestions:

module.exports = {
  themeConfig: {
    search: false,
    searchMaxSuggestions: 10,
  },
};
1
2
3
4
5
6

You can also disable the built-in search box for individual pages with YAML front matter:

---
search: false
---
1
2
3

Tips

Built-in Search only builds index from the title, h2 and h3 headers, if you need full text search, you can use Algolia DocSearch.

# Algolia DocSearch

The themeConfig.algolia option allows you to use Algolia DocSearch (opens new window) to replace the simple built-in search. To enable it, you need to provide at least apiKey and indexName:

module.exports = {
  themeConfig: {
    algolia: {
      apiKey: "<API_KEY>",
      indexName: "<INDEX_NAME>",
    },
  },
};
1
2
3
4
5
6
7
8

Note

Unlike the built-in search engine which works out of the box, Algolia DocSearch (opens new window) requires you to submit your site to them for indexing before it starts working.

For more options, check out Algolia DocSearch’s documentation (opens new window).

# Search Placeholder

You can define a placeholder for the search box by adding the searchPlaceholder attribute:

module.exports = {
  themeConfig: {
    searchPlaceholder: "Search...",
  },
};
1
2
3
4
5

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",
    // Customising the header label
    // Defaults to "GitHub"/"GitLab"/"Bitbucket" depending on `themeConfig.repo`
    repoLabel: "Contribute!",
    // Whether to display repo link, default is `true`
    repoDisplay: true,

    // Optional options for generating "Edit this page" link

    // if your docs are in a different repo from your main project:
    docsRepo: "vuejs/vuepress",
    // if your docs are not at the root of the repo:
    docsDir: "docs",
    // if your docs are in a specific branch (defaults to 'main'):
    docsBranch: "main",
    // defaults to false, set to true to enable
    editLinks: true,
    // default value is true. Allows to hide next page links on all pages
    nextLinks: false,
    // default value is true. Allows to hide prev page links on all pages
    prevLinks: false,
    // custom text for edit link. Defaults to "Edit this page"
    editLinkText: "Help us improve this page!",
  },
};
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

You can overwrite the following properties on specific pages via YAML front matter:

---
editLink: false # Will overwrite 'editLinks' from themeConfig
---
1
2
3

# Theme color button

For details, see the Themecolor section.

# Darkmode button

For details, see the Darkmode section.

# Full screen button

For details, see the Full Screen Button section.

We provide a navbarConfig 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 navbar configuration.

// .vuepress/navbar.js
const { navbarConfig } = require("vuepress-theme-hope");

module.exports = navbarConfig(/* Your navbar configuration */);
1
2
3
4

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
// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: "Guide", link: "/guide/", icon: "creative" },
      { text: "Config", link: "/config/", icon: "config" },
      { text: "FAQ", link: "/FAQ/", icon: "question" },
      {
        text: "Basic",
        icon: "info",
        prefix: "/basic/",
        items: [
          { text: "Markdown", link: "markdown/", icon: "markdown" },
          { text: "VuePress", link: "vuepress/", icon: "vue" },
        ],
      },
      {
        text: "Project",
        icon: "info",
        items: [
          {
            text: "Changelog",
            link:
              "https://github.com/vuepress-theme-hope/vuepress-theme-hope/blob/v1/CHANGELOG.md",
          },
          {
            text: "Repo",
            link: "https://github.com/vuepress-theme-hope/vuepress-theme-hope",
          },
          {
            text: "Theme Demo",
            link: "/demo/",
          },
          {
            text: "Plugins",
            icon: "plugin",
            items: [
              {
                text: "AddThis Plugin",
                link: "https://vuepress-theme-hope.github.io/add-this/",
              },
              {
                text: "Comment Plugin",
                link: "https://vuepress-theme-hope.github.io/comment/",
              },
              {
                text: "Copy Code Plugin",
                link: "https://vuepress-theme-hope.github.io/copy-code/",
              },
              {
                text: "Feed Plugin",
                link: "https://vuepress-theme-hope.github.io/feed/",
              },
              {
                text: "Git Info Plugin",
                link: "https://vuepress-theme-hope.github.io/git/",
              },
              {
                text: "Markdown Enhance Plugin",
                link: "https://vuepress-theme-hope.github.io/md-enhance/",
              },
              {
                text: "Photo Swipe Plugin",
                link: "https://vuepress-theme-hope.github.io/photo-swipe/",
              },
              {
                text: "PWA Plugin",
                link: "https://vuepress-theme-hope.github.io/pwa/",
              },
              {
                text: "Reading Time Plugin",
                link: "https://vuepress-theme-hope.github.io/reading-time/",
              },
              {
                text: "Seo Plugin",
                link: "https://vuepress-theme-hope.github.io/seo/",
              },
              {
                text: "Sitemap Plugin",
                link: "https://vuepress-theme-hope.github.io/sitemap/",
              },
            ],
          },
        ],
      },
    ],
  },
};
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