Organize Navigation

The navigation editor lets you organize your documentation structure visually. Changes you make in the navigation tree automatically sync to your docs.json configuration file and appear in your site’s navigation sidebar.

​

Add Navigation Elements

Create new navigation elements to organize your documentation: Add top-level elements: Click Add new at the bottom of the navigation tree Add nested elements: Click the plus button next to an existing element After creating an element, you can:

• Drag and drop to reorder or nest elements
• Hover and click the gear icon to configure properties
• Right-click to access options like duplicate, convert, or delete

​

Navigation Element Types

Choose the right navigation structure for your documentation:

​

Pages

Individual documentation files that contain your content. When to use: Pages are the core building blocks—every piece of content lives on a page. Add pages to your navigation to make them visible in your site’s sidebar. Where they can exist: At the root level, within groups, tabs, anchors, dropdowns, or menus.

​

Groups

Collapsible sections that organize related pages together. When to use: Group related pages to help users scan your navigation, like clustering all authentication-related pages or API endpoint references. Nesting: Groups can nest within other groups for hierarchical organization. They can exist within tabs, anchors, dropdowns, or at the root level.

​

Tabs

Top-level sections with horizontal navigation at the top of your site. When to use: Create distinct areas like “API Reference,” “Guides,” and “SDKs” that users need to switch between. Contents: Tabs can contain pages, groups, and menu items. Configure tabs to add icons or link to external resources.

​

Anchors

Persistent navigation items at the top of your sidebar. When to use: Section your content or provide quick access to important pages without switching tabs. Contents: Anchors can contain pages and groups, or link to external URLs. Global anchors: Create anchors that appear on all pages regardless of section. Global anchors must link to external URLs and are useful for resources like blogs, status pages, or support links.

​

Dropdowns

Expandable menus at the top of your sidebar. When to use: Organize multiple related sections that users might explore but don’t need constant visibility like tabs. Contents: Dropdowns can contain pages and groups, or link to external URLs.

​

Menus

Dropdown navigation items within tabs. When to use: Let users navigate directly to specific pages from the top navigation bar. Contents: Menus can contain pages and groups.

​

Products

Switcher menu for multiple distinct product offerings. When to use: Your organization has multiple products that each need their own documentation. Structure: Each product can have its own navigation structure with tabs, pages, and groups.

​

Versions

Switcher menu for multiple documentation versions. When to use: You maintain multiple versions simultaneously, like v1.0, v2.0, and v3.0 of an API. Structure: Each version can have different content and navigation structure.

​

Languages

Switcher menu for multilingual documentation. When to use: You provide documentation in multiple languages. Structure: Each language maintains the same navigation structure with translated content.

​

Customize Navigation Appearance

Make your navigation more visual and user-friendly:

​

Add Icons

1. Hover over a navigation item
2. Click the gear icon
3. Click the icon field and select an icon

Icons provide visual markers that help users quickly identify sections.

​

Add Tags

1. Hover over a navigation item
2. Click the gear icon
3. Click the tag field
4. Enter a tag like “NEW” or “BETA”

Tags highlight important or recently updated items in your navigation.

​

Control Visibility

Hide content within a navigation element without deleting it:

1. Right-click the item
2. Click the toggle by the Hide label

Hidden elements remain in your repository but don’t appear in the published navigation.

​

Working with the Navigation Tree

​

Reorder Elements

Drag and drop elements to change their order. The new order appears immediately in your site’s navigation and syncs to docs.json.

​

Nest Elements

Drag an element onto another element to nest it. Valid drop zones highlight as you drag.

​

Duplicate Elements

Right-click an element and select Duplicate to create a copy with the same configuration.

​

Convert Elements

Right-click an element and select Convert to to change it to a different navigation type while preserving its contents.

​

Delete Elements

Right-click an element and select Delete. Deleting a navigation element removes it from your docs.json but doesn’t delete the actual files from your repository.

​

Best Practices

​

Keep Navigation Shallow

Limit nesting to 2-3 levels deep. Deeply nested navigation makes it harder for users to find content.

​

Use Consistent Patterns

Apply the same navigation structure across similar sections. Consistency helps users learn how to navigate your documentation.

​

Group Related Content

Organize pages by user goals or topics rather than technical boundaries. Think about how users will search for information.

​

Test Your Structure

Use the live preview to see how your navigation appears to users. Make sure the most important content is easy to find.

​

Navigation and Git

Navigation changes sync to your docs.json file:

• When you save changes on a deployment branch, navigation updates deploy immediately
• When you save changes on a feature branch, navigation updates are included in your pull request
• Navigation changes are tracked in Git along with content changes

You can see navigation changes in the files changed dropdown and in your Git diff when reviewing pull requests.