Skip to main content

Navbar Configuration

Learn how to configure and customize the top navigation bar in Docusaurus.

Overview​

The navbar is configured in docusaurus.config.js under the themeConfig.navbar section. It controls the main navigation menu at the top of your site.

Basic Structure​

navbar: {
  title: 'Home',
  items: [
    // Menu items go here
  ],
}

1. Dropdown Menu​

Create a dropdown menu with multiple sub-items:

{
  'type': 'dropdown',
  'label': 'Code',
  'position': 'left',
  'items': [
    { 
      'type': 'doc', 
      'docId': 'code/html/index', 
      'sidebarId': 'codeHtmlSidebar', 
      'label': 'HTML' 
    },
    { 
      'type': 'doc', 
      'docId': 'code/css/index', 
      'sidebarId': 'codeCssSidebar', 
      'label': 'CSS' 
    }
  ]
}

Link directly to a page:

{
  'to': '/blog',
  'label': 'Blog',
  'position': 'left'
}

Link to a document and activate its sidebar:

{
  'type': 'doc',
  'docId': 'wordpress/generatepress/index',
  'sidebarId': 'wpGeneratepressSidebar',
  'label': 'Generatepress'
}

Important Notes​

Nested Dropdowns Not Supported​

Docusaurus does not support nested dropdowns in the navbar. This will cause a build error:

// ❌ This will FAIL
{
  'type': 'dropdown',
  'label': 'Parent',
  'items': [
    {
      'type': 'dropdown',  // Nested dropdown - NOT ALLOWED
      'label': 'Child',
      'items': [...]
    }
  ]
}

Workaround: Visual Grouping​

You can use HTML items to create visual grouping:

{
  'type': 'dropdown',
  'label': 'Visual Editing',
  'items': [
    { 'html': '<b style="color: #25c2a0;">GUIDELINES</b>', 'to': '#' },
    { 'type': 'doc', 'docId': 'design-editing/guidelines/web-design', 'label': 'Web Design' },
    { 'html': '<hr style="margin: 0.3rem 0;" />', 'to': '#' },
    { 'html': '<b style="color: #25c2a0;">PLATFORM</b>', 'to': '#' },
    { 'type': 'doc', 'docId': 'design-editing/platform/canva', 'label': 'Canva' }
  ]
}

Renaming Menu Items​

To rename a menu item, simply change the label property:

// Before
{ 'label': 'My Documentation' }

// After
{ 'label': 'Home' }

Removing Menu Items​

To remove a menu item, delete its entire object from the items array:

// Remove this entire block
{
  'to': '/blog',
  'label': 'Blog',
  'position': 'left'
},

Best Practices​

  1. Keep labels short - Long labels can break the layout on mobile devices
  2. Use consistent positioning - Most items should be 'position': 'left'
  3. Link to index pages - Always use /index for main section pages
  4. Match sidebar IDs - Ensure sidebarId matches the sidebar name in sidebars.js

Common Issues​

Problem: Added a menu item but it doesn't show up.

Solution: Check that:

  • The document file exists at the specified docId path
  • The sidebar ID exists in sidebars.js
  • There are no syntax errors in the configuration

502 Bad Gateway After Changes​

Problem: Site shows 502 error after navbar changes.

Solution:

  • Check Docker logs: sudo docker logs docusaurus --tail 50
  • Look for missing document errors
  • Verify all referenced files exist
  • Restart container: sudo docker restart docusaurus