Organize navigation

The navigation sidebar controls how your documentation is organized. Changes you make in the web editor’s navigation tree appear in your site’s navigation sidebar and sync to your docs.json configuration file.

​

Add navigation elements

Click the Add new button at the bottom of the navigation tree to add a new navigation element. To add a navigation element nested inside another element, click the + button next to the name of the parent element. After creating an element, drag and drop it to reorder or nest it within other elements. Right-click any element to configure its properties, duplicate it, hide it from navigation, or delete it.

​

Organize into sections

Choose the right navigation structure for your documentation’s scope and audience.

​

When to use pages

Use pages for individual documentation files. Pages are the core building blocks of your navigation—every piece of content lives on a page. Add pages to your navigation to make them visible in your site’s sidebar. Pages can exist at the root level, within groups, tabs, anchors, dropdowns, or menus.

​

When to use groups

Use groups to organize related pages into collapsible sections. Groups help users scan your navigation by clustering similar content together, like grouping all authentication-related pages or all API endpoint references. Groups can be nested within other groups to create hierarchical organization. Groups can exist within tabs, anchors, dropdowns, or at the root level.

​

When to use tabs

Use tabs to create separate top-level sections with horizontal navigation at the top of your site. Tabs work well when you have distinct areas like API Reference, Guides, and SDKs that users need to switch between. Tabs can contain pages, groups, and menu items. Configure tabs to add icons or link to external resources.

​

When to use anchors

Use anchors to create persistent navigation items at the top of your sidebar. Anchors help when you want to section your content or provide quick access to external resources without switching tabs. Anchors can contain pages and groups, or link to external URLs. Global anchors: Create global anchors that appear on all pages regardless of which section users are viewing. Global anchors must link to external URLs and are useful for resources like blogs, status pages, or support links.

​

When to use dropdowns

Use dropdowns to create an expandable menu at the top of your sidebar. Dropdowns work well when you have multiple related sections that users might want to explore but don’t need constant visibility like tabs. Dropdowns can contain pages and groups, or link to external URLs.

​

When to use menus

Use menus to add dropdown navigation items within a tab. Menus help users navigate directly to specific pages from the top navigation bar. Menus can contain pages and groups.

​

When to use products

Use products when you have multiple distinct product offerings that each need their own documentation. Products create a switcher menu that lets users navigate between different product documentation sets. Each product can have its own navigation structure with tabs, pages, and groups.

​

When to use versions

Use versions when you maintain multiple versions of your documentation simultaneously, like v1.0, v2.0, and v3.0 of an API. Versions create a switcher menu that lets users select which version they want to view. Each version can have different content and navigation structure.

​

When to use languages

Use languages when you provide documentation in multiple languages. Languages create a switcher menu that lets users view documentation in their preferred language. Each language maintains the same navigation structure with translated content.

​

Customize appearance

Add icons:

1. Right-click a navigation item.
2. Click Configure.
3. Click the icon field.

Add tags:

1. Right-click a navigation item.
2. Click Configure.
3. Click the tag field.
4. Enter a tag like “NEW” or “BETA” that highlights important items.

Control visibility: Hide the content within a navigation element without deleting it from your repository.

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