Create top navigation menu in Docusaurus

Docusaurus provides the sidebar Docs menu by default. You don’t need to edit the sidebar.js file, the pages are built automatically using the folder structure. If you wish to add the top navigation menu items, you need to add other sidebars. It’s not just a link to an external site like GitHub or Blog. When you click the top navigation menu item, you see another sidebar menu and sections similar to your default Docs sidebar menu.

  5 minute read  

The goal is to add the top navigation menu items each having their own sidebar menu. The sidebar must use automatic folder structure. See the API top navbar item in Docusaurus site as an example of the result.

Prerequisites

To add the top navigation menu to Docusaurus, make sure you have Docusaurus installed:

  • To check that you have Node.js installed: node --version. If you don’t see the version, download and install Node.js.
  • To check that you have Docusaurus installed: npx docusaurus --version. If you don’t see the version, follow the installation instructions here.

I assume that you’ve installed your Docusaurus. Open the project folder in VS Code or any other IDE of your liking. For these instructions, I’m using my test Docusaurus project:

Add top navigation menu items

By default, a Docusaurus site doesn’t have the top navigation menu other than Docs.

Default Docusaurus navbar

To add another top navigation menu item with its own sidebar, your docs folder must include a separate folder for each sidebar. Make sure you have separate folders with .md files in the docs folder.

  1. Copy the existing folders and files in the docs folder to a separate folder, for example, default-docs. Now, the path to the existing Docusaurus files is docs/default-docs.

  2. Add another folder to the docs folder, for example, docs/test.

  3. Add your .md files and folders to the docs/test folder.

  4. Add two items to the navbar in the docusaurus.config.js file:

    items: [
  {
    type: "docSidebar",
    sidebarId: "defaultSidebar",
    position: "left",
    label: "Docs",
  },
  {
    type: "docSidebar",
    sidebarId: "newSidebar",
    position: "left",
    label: "Test",
  },
],

    where:

    • type is the type of the navigation menu item: docSidebar.

    • sidebarId is a unique ID of your sidebar, for example, defaultSidebar or newSidebar. You can create your own ID.

    • position is the position to the left (default) or to the right in the top navbar.

    • label is the actual name displayed in the top navbar: Docs, Test, you name it.

    Click here to view the entire docusaurus.config.js file. 
    // @ts-check
// Note: type annotations allow type checking and IDEs autocompletion



/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'Documentation site',
  tagline: 'How to create your documentation site with Docusaurus',
  url: 'https://ivan-documentation-example.netlify.app',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'ivancheban', // Usually your GitHub org/user name.
  projectName: 'my-site', // Usually your repo name.

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          editUrl: 'https://github.com/ivancheban/my-site/edit/master/',
        },
        gtag: {
          trackingID: 'G-NJKPS9HXWM',
          anonymizeIP: true,
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          editUrl:
            'https://github.com/ivancheban/my-site/edit/master/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

  plugins: [
    require.resolve('docusaurus-plugin-image-zoom'),
    require.resolve('docusaurus-lunr-search')
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: 'Documentation site',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: "docSidebar",
            sidebarId: "defaultSidebar",
            position: "left",
            label: "Docs",
          },
          {
            type: "docSidebar",
            sidebarId: "newSidebar",
            position: "left",
            label: "Test",
          },
//          {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/ivancheban/my-site',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      zoom: {
        selector: '.markdown :not(em) > img',
        background: {
          light: 'rgb(255, 255, 255)',
          dark: 'rgb(50, 50, 50)'
        },
        config: {
          // options you can specify via https://github.com/francoischalifour/medium-zoom#usage
        }
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Docs',
            items: [
              {
                label: 'Tutorial',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Community',
            items: [
              {
                label: 'Stack Overflow',
                href: 'https://stackoverflow.com/questions/tagged/docusaurus',
              },
              {
                label: 'Discord',
                href: 'https://discordapp.com/invite/docusaurus',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/docusaurus',
              },
            ],
          },
          {
            title: 'More',
            items: [
              {
                label: 'Blog',
                to: '/blog',
              },
              {
                label: 'GitHub',
                href: 'https://github.com/facebook/docusaurus',
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
      },
    }),
};

module.exports = config;

  5. Add your sidebars to the sidebars.js file, using the sidebarId value for each of your sidebars.

    const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  defaultSidebar: [{type: 'autogenerated', dirName: 'default-docs'}],
  newSidebar: [{type: 'autogenerated', dirName: 'test'}],
};

    where:

    • type is autogenerated meaning that folder structure is used for generating the sidebar from .md files. You control the hierarchy using the front matter sidebar_position value.

    • dirName is the name of the folder with .md files, for example, default-docs or test folder.

    Click here to view the entire sidebars.js file. 
    /**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation

The sidebars can be generated from the filesystem, or explicitly defined here.

Create as many sidebars as you want.
*/

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  defaultSidebar: [{type: 'autogenerated', dirName: 'default-docs'}],
  newSidebar: [{type: 'autogenerated', dirName: 'test'}],

  // But you can create a sidebar manually
  /*
  tutorialSidebar: [
    {
      type: 'category',
      label: 'Tutorial',
      items: ['hello'],
    },
  ],
  */
};

module.exports = sidebars;

As the result, the top navigation bar now has two items: Docs and Test. Each of these items has its own sidebar that’s built automatically from the .md files in the separate folders of the docs folder.

Two sidebars

First sidebar

Each sidebar may have subsections based on the subfolders with the _category_.json file. See the default Docusaurus tutorial-basics and tutorial-extras folders.

View the real-world example here:

Ask chatbot

Last modified January 7, 2025: added an article about top navbar in Docusaurus (53f0ed1)