Skip to main content

NavBar

About 5 minLayoutLayoutNavbar

The Navbar may contain your site title, Search Box, Navbar Links, I18nopen in new window, Repository Link and Outlook Popup. They all depend on your configuration.

You can add links to the navbar via navbar options, it accepts an array.

String Format

The easiest way to configure the navbar is to fill in the paths of the page files to be displayed in turn, so that the text, icons and links of the item will be automatically generated from the corresponding files.

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: ["/guide/README.md", "/config/README.md", "/faq.md"],
  }),
});

Tips

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

Object Format

If you are not satisfied with the page's icon or feel that the page title is too long, you can configure an object instead. Available configuration items are:

  • text:: item text
  • link: item link
  • icon: item icon (optional)
  • activeMatch: item active math (optional), support regexp strings
// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "Guide",
        link: "/guide/README.md",
        icon: "lightbulb",
        // only active in `/guide/`
        activeMatch: "^/guide/$",
      },
      { text: "Config", link: "/config/README.md", icon: "config" },
      {
        text: "FAQ",
        link: "/faq.md",
        icon: "circle-question",
        // active in path starting with `/faq`
        // so it will active in path like `/faq/xxx.html`
        activeMatch: "^/zh/faq/",
      },
    ],
  }),
});

Advanced usage of activeMatch

activeMatch gives you the ability to control whether the path is active, for example you may have the following dropdown:

  • /path/
  • /path/a/
  • /path/b/

But you may have multiple folders with files under /path/. To avoid multiple dropdown items been activated under route starting with /path/a/ or /path/b/, you can set activeMatch option for the first item with ^/path/(?:(?!a/|b/).*)?$.

To display more links, you can group similar links into a dropdown list.

You need to use object format and provide the additional children option to nest links:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "Basic",
        icon: "circle-info",
        children: ["/basic/markdown.md", "/basic/vuepress.md"],
      },
    ],
  }),
});

In most cases, the grouped items in the navbar 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.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "Basic",
        icon: "circle-info",
        prefix: "/basic/",
        children: ["markdown.md", "vuepress.md"],
      },
    ],
  }),
});

You can also have subgroups inside a dropdown by having nested children:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "Project",
        icon: "circle-info",
        children: [
          {
            text: "Built in Plugins",
            icon: "puzzle-piece",
            children: [
              /* Some items */
            ],
          },
          {
            text: "Third party Plugins",
            icon: "puzzle-piece",
            children: [
              /* Some items */
            ],
          },
        ],
      },
    ],
  }),
});

Disable Navbar

To disable the navbar globally, set navbar: false in theme options:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: false,
  }),
});

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

---
navbar: false
---

Disable Navbar Icon

To disable the navbar icon, set navbarIcon: false in theme options:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbarIcon: false,
  }),
});

You can use logo options to set site logo displayed in navbar.

The logo is displayed on the navbar instead of the previous site name on mobile.

Note

Please fill in an absolute path and place the logo in .vuepress/public folder.

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    logo: "/logo.png",
  }),
});

Tips

You can set logoDark to display another logo in dark mode.

I18n Support

The theme's navbar supports I18nopen in new window, so you can set navbar options mentioned above individually in each language:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    locales: {
      "/": {
        logo: "/logo.svg",
        navbar: [
          /* English config under root */
        ],
      },
      "/zh/": {
        logo: "/zh-logo.svg",
        navbar: [
          /* Chinese config under zh folder */
        ],
      },
    },
  }),
});

Like the default theme, vuepress-theme-hope brings built-in support for search plugins. You can enable the following plugins according to your own needs. The corresponding search box will automatically appear in the navbar.

For details, please see Feature → Search.

A repo button will appear in navbar if you set repo in theme options.

You can control whether showing the repository button via repoDisplay in theme options.

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    // Assumes GitHub. Can also be a full GitLab url.
    repo: "vuepress-theme-hope/vuepress-theme-hope",
    // Customizing the header label
    // Defaults to "GitHub" / "GitLab" / "Gitee" / "Bitbucket" or "Source" depending on `repo`
    repoLabel: "GitHub",
    // Whether to display repo link, default is `true`
    repoDisplay: true,
  }),
});

Outlook Popup

The following three functions are provided:

Layout config

vuepress-theme-hope allows you to customize navbar layout. You can add components in start, center and end keys under navbarLayout options.

Besides global components, the following built-in components are supported:

  • Brand: Site Brand
  • Links: Navbar links
  • Language: Language Switcher
  • Search: Search Box
  • Outlook: Outlook Popup
  • Repo: Project Repo

By default, we are using the following options:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbarLayout: {
      start: ["Brand"],
      center: ["Links"],
      end: ["Language", "Repo", "Outlook", "Search"],
    },
  }),
});

Types and Helpers

vuepress-theme-hope exports the type of navbar as NavbarConfig, and provides a navbar helper function. They can provide validation and autocompletion of navbar configuration in TS and JS.

Tips

They mainly deal with scenarios when you split your VuePress configuration into multiple parts.

// .vuepress/navbar.ts
import { navbar } from "vuepress-theme-hope";

export default navbar([
  /* Your navbar configuration */
]);

Demo

Configuration of this documentation
import { navbar } from "vuepress-theme-hope";


const linkHelper = getLinkHelper();

export const enNavbarConfig = navbar([
  "/guide/",
  "/config/",
  "/faq/",
  {
    text: "Cookbook",
    icon: "signs-post",
    prefix: "/cookbook/",
    children: ["tutorial/", "markdown/", "vuepress/", "customize/"],
  },
  "/migration/",
  {
    text: "Project",
    icon: "circle-info",
    children: [
      "/changelog",
      "/demo/",
      "/contribution",
      {
        text: "Plugins",
        icon: "puzzle-piece",
        children: [
          {
            text: "Auto catalog Plugin",
            icon: "network-wired",
            link: linkHelper("auto-catalog"),
          },
          {
            text: "Blog Plugin",
            icon: "blog",
            link: linkHelper("blog2"),
          },
          {
            text: "Comment Plugin",
            icon: "comment",
            link: linkHelper("comment2"),
          },
          {
            text: "Components Plugin",
            icon: "puzzle-piece",
            link: linkHelper("components"),
          },
          {
            text: "Copy Code Plugin",
            icon: "copy",
            link: linkHelper("copy-code2"),
          },
          {
            text: "Copyright Plugin",
            icon: "copyright",
            link: linkHelper("copyright2"),
          },
          {
            text: "Feed Plugin",
            icon: "rss",
            link: linkHelper("feed2"),
          },
          {
            text: "LightGallery Plugin",
            icon: "image",
            link: linkHelper("lightgallery"),
          },
          {
            text: "Markdown Enhance Plugin",
            icon: "fab fa-markdown",
            link: linkHelper("md-enhance"),
          },
          {
            text: "Photo Swipe Plugin",
            icon: "image",
            link: linkHelper("photo-swipe"),
          },
          {
            text: "PWA Plugin",
            icon: "mobile",
            link: linkHelper("pwa2"),
          },
          {
            text: "Reading Time Plugin",
            icon: "book-open",
            link: linkHelper("reading-time2"),
          },
          {
            text: "Remove PWA Plugin",
            icon: "trash-can",
            link: linkHelper("remove-pwa"),
          },
          {
            text: "Redirect Plugin",
            icon: "fas fa-eject fa-rotate-90",
            link: linkHelper("redirect"),
          },
          {
            text: "Sass Palette Plugin",
            icon: "palette",
            link: linkHelper("sass-palette"),
          },
          {
            text: "Client Search Plugin",
            icon: "search",
            link: linkHelper("search-pro"),
          },
          {
            text: "Seo Plugin",
            icon: "wrench",
            link: linkHelper("seo2"),
          },
          {
            text: "VuePress shared",
            icon: "toolbox",
            link: linkHelper("shared"),
          },
          {
            text: "Sitemap Plugin",
            icon: "sitemap",
            link: linkHelper("sitemap2"),
          },
        ],
      },
    ],
  },
]);
MIT Licensed | Copyright © 2019-present Mr.Hope