Navigation

One of the most important pieces of making a working site is to define your navigation items. This allows the theme to inform the SideNav component as well as the next/previous components at the bottom of each page.

Yaml data

Unfortunately, genenerating left nav contents purely from the pages directory has some fatal flaws. It makes it very difficult to establish the order of items or to hide items all together. In src/data/nav-items.yaml, you’ll list your nav items in order.

- title: Menu
  pages:
    - title: Page 1
      path: /menu/Page-1
    - title: Page 2
      path: /menu/Page-2
- title: Single Page
  pages:
    - path: /single-page

Some important things to note here:

You only need to link to the first tab if using page tabs
The title refers to the menu and item text, it’s allowed to have spaces
The path refer to the relative path to the mdx file in your pages
You can make a Page/index.mdx file if you’d prefer to have assets in a folder. The path would still just look like /Page

Adding a divider

You can add divider(s) between the items of your nav item list by adding hasDivider: true in src/data/nav-items.yaml. Note the divider is only for top-level nav items and can only be used with the left sidebar navigation style. It cannot be used in conjunction with the header navigation style.

- title: Menu
  pages:
    - title: Page 1
      path: /menu/Page-1
    - title: Page 2
      path: /menu/Page-2
  hasDivider: true
- title: Single Page
  pages:

In the example above, a divider will appear between Menu and Single Page.

Customizing

The nav item list can be customized using Gatsby theme shadowing. Simply provide your own implementation of /src/util/NavItems.js which can augment or replace the nav items read from src/data/nav-items.yaml.

// /src/util/NavItems.js
import { useNavItems as themeUseNavItems } from 'gatsby-theme-carbon/src/util/NavItems';
// add nav items
export function useNavItems() {
  const navItems = themeUseNavItems();
  return navItems.concat({
    title: 'Additional Nav Item',
    pages: [

Edit this page on GitHub

Guides: Styling

Navigation: Tabs