导航栏

Mr.Hope ... 2020年10月13日 13:36 Layout
  • Layout
  • Navbar
大约 6 分钟

导航栏可能包含你的站点名称、搜索框导航栏链接多语言切换 (opens new window)仓库链接,它们均取决于你的配置。

# 导航栏链接

你可以通过 themeConfig.nav 增加一些导航栏链接。

基础的配置项有 text 导航栏文字,link 导航栏链接, icon 导航栏图标:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: "指南", link: "/zh/guide/", icon: "creative" },
      { text: "配置", link: "/zh/config/", icon: "config" },
      { text: "常见问题", link: "/zh/FAQ/", icon: "question" },
    ],
  },
};
1
2
3
4
5
6
7
8
9
10

当你提供了一个 items 数组而不是一个单一的 link 时,它将显示为下拉列表 :

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

由于大多数情况下,导航栏的分组项目都属于同一类别,会放在同一个子目录下,它们具有相同的路径前缀。为了简化配置,你可以添加 prefix 字段为分组的每一个子链接添加一个前缀:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      {
        text: "基础",
        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

此外,你还可以通过嵌套的 items 来在下拉列表中设置分组:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: "项目",
        icon: "info",
        items: [
          {
            text: "内置插件",
            icon: "plugin",
            items: [
              /* 一些子项目 */
            ],
          },
          {
            text: "引入插件",
            icon: "plugin",
            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
例子
// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      {
        text: "项目",
        icon: "info",
        items: [
          {
            text: "更新日志",
            link:
              "https://github.com/vuepress-theme-hope/vuepress-theme-hope/blob/v1/CHANGELOG.md",
          },
          {
            text: "项目地址",
            link: "https://github.com/vuepress-theme-hope/vuepress-theme-hope",
          },
          {
            text: "项目案例",
            link: "/zh/demo/",
          },
          {
            text: "插件",
            icon: "plugin",
            items: [
              {
                text: "AddThis 插件",
                link: "https://vuepress-theme-hope.github.io/add-this/zh/",
              },
              {
                text: "评论插件",
                link: "https://vuepress-theme-hope.github.io/comment/zh/",
              },
              {
                text: "代码复制插件",
                link: "https://vuepress-theme-hope.github.io/copy-code/zh/",
              },
              {
                text: "Feed 插件",
                link: "https://vuepress-theme-hope.github.io/feed/zh/",
              },
              {
                text: "Git 信息插件",
                link: "https://vuepress-theme-hope.github.io/git/zh/",
              },
              {
                text: "Markdown 增强插件",
                link: "https://vuepress-theme-hope.github.io/md-enhance/zh/",
              },
              {
                text: "图片预览插件",
                link: "https://vuepress-theme-hope.github.io/photo-swipe/zh/",
              },
              {
                text: "PWA 插件",
                link: "https://vuepress-theme-hope.github.io/pwa/zh/",
              },
              {
                text: "阅读时间插件",
                link: "https://vuepress-theme-hope.github.io/reading-time/zh/",
              },
              {
                text: "Seo 插件",
                link: "https://vuepress-theme-hope.github.io/seo/zh/",
              },
              {
                text: "Sitemap 插件",
                link: "https://vuepress-theme-hope.github.io/sitemap/zh/",
              },
            ],
          },
        ],
      },
    ],
  },
};
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

# 禁用导航栏

你可以使用 themeConfig.navbar 来禁用所有页面的导航栏:

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

你也可以通过 YAML front matter 来禁用某个指定页面的导航栏:

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

# 导航栏图标

你可以使用 themeConfig.logo 来配置导航栏的图标,请填入绝对路径。

当配置图标之后,在移动视图上,图标将取代先前的站点名称显示在导航栏上。

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

提示

你可以设置 themeConfig.darkLogo 以在暗黑模式下显示另一个 Logo。

# 搜索框

# 内置搜索

你可以通过设置 themeConfig.search: false 来禁用默认的搜索框,或是通过 themeConfig.searchMaxSuggestions 来调整默认搜索框显示的搜索结果数量:

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

你可以通过 YAML front matter 来对单独的页面禁用内置的搜索框:

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

提示

内置搜索只会为页面的标题、h2h3 构建搜索索引,如果你需要全文搜索,你可以使用 Algolia 搜索

# Algolia 搜索

你可以通过 themeConfig.algolia 选项来用 Algolia 搜索 (opens new window) 替换内置的搜索框。要启用 Algolia 搜索,你需要至少提供 apiKeyindexName:

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

注意

不同于开箱即用的 内置搜索Algolia 搜索 (opens new window) 需要你在使用之前将你的网站提交给它们用于创建索引。

更多选项请参考 Algolia DocSearch 的文档 (opens new window)

# 搜索占位符

你可以通过添加 searchPlaceholder 属性为搜索框定义一个占位符:

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

# Git 仓库和编辑链接

当你提供了 themeConfig.repo 选项,将会自动在每个页面的导航栏生成生成一个 GitHub 链接,以及在页面的底部生成一个 "Edit this page" 链接。

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // 假定是 GitHub. 同时也可以是一个完整的 GitLab URL
    repo: "vuejs/vuepress",
    // 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为
    // "GitHub"/"GitLab"/"Bitbucket" 其中之一,或是 "Source"。
    repoLabel: "查看源码",
    // 是否在导航栏右侧显示仓库链接,默认为 `true`
    repoDisplay: true,

    // 以下为可选的编辑链接选项

    // 假如你的文档仓库和项目本身不在一个仓库:
    docsRepo: "vuejs/vuepress",
    // 假如文档不是放在仓库的根目录下:
    docsDir: "docs",
    // 假如文档放在一个特定的分支下,默认为 'main':
    docsBranch: "main",
    // 默认是 false, 设置为 true 来启用
    editLinks: true,
    // 默认为 "Edit this page"
    editLinkText: "帮助我们改善此页面!",
  },
};
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

你可以通过 YAML front matter 来禁用指定页面的编辑链接:

---
editLink: false
---
1
2
3

# 主题色切换按钮

具体详情请见 主题色 章节。

# 深色模式切换按钮

具体详情请见 深色模式 章节。

# 全屏按钮

具体详情请见 全屏按钮 章节。

我们提供了一个 navbarConfig Helper 函数。你可以从 vuepress-theme-hope 中将其引入,并包裹你的导航栏配置来让编辑器提供自动补全并帮助你校验导航栏配置是否正确。

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

module.exports = navbarConfig(/* 你的导航栏配置 */);
1
2
3
4

提示

当你将 vuepress 配置拆分成多个部分时,你可以使用该 Helper 函数来保持自动补全与校验。

# 案例

本文档的导航栏配置
// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: "指南", link: "/zh/guide/", icon: "creative" },
      { text: "配置", link: "/zh/config/", icon: "config" },
      { text: "常见问题", link: "/zh/FAQ/", icon: "question" },
      {
        text: "基础",
        icon: "info",
        prefix: "/zh/basic/",
        items: [
          { text: "Markdown", link: "markdown/", icon: "markdown" },
          { text: "VuePress", link: "vuepress/", icon: "vue" },
        ],
      },
      {
        text: "项目",
        icon: "info",
        items: [
          {
            text: "更新日志",
            link:
              "https://github.com/vuepress-theme-hope/vuepress-theme-hope/blob/v1/CHANGELOG.md",
          },
          {
            text: "项目地址",
            link: "https://github.com/vuepress-theme-hope/vuepress-theme-hope",
          },
          {
            text: "项目案例",
            link: "/zh/demo/",
          },
          {
            text: "插件",
            icon: "plugin",
            items: [
              {
                text: "AddThis 插件",
                link: "https://vuepress-theme-hope.github.io/add-this/zh/",
              },
              {
                text: "评论插件",
                link: "https://vuepress-theme-hope.github.io/comment/zh/",
              },
              {
                text: "代码复制插件",
                link: "https://vuepress-theme-hope.github.io/copy-code/zh/",
              },
              {
                text: "Feed 插件",
                link: "https://vuepress-theme-hope.github.io/feed/zh/",
              },
              {
                text: "Git 信息插件",
                link: "https://vuepress-theme-hope.github.io/git/zh/",
              },
              {
                text: "Markdown 增强插件",
                link: "https://vuepress-theme-hope.github.io/md-enhance/zh/",
              },
              {
                text: "图片预览插件",
                link: "https://vuepress-theme-hope.github.io/photo-swipe/zh/",
              },
              {
                text: "PWA 插件",
                link: "https://vuepress-theme-hope.github.io/pwa/zh/",
              },
              {
                text: "阅读时间插件",
                link: "https://vuepress-theme-hope.github.io/reading-time/zh/",
              },
              {
                text: "Seo 插件",
                link: "https://vuepress-theme-hope.github.io/seo/zh/",
              },
              {
                text: "Sitemap 插件",
                link: "https://vuepress-theme-hope.github.io/sitemap/zh/",
              },
            ],
          },
        ],
      },
    ],
  },
};
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