Configuring Navigation and Sidebar

Relevant source files

The following files were used as context for generating this wiki page:

• docs.json
• README.md
• api-reference/openapi.json
• essentials/navigation.mdx (inferred from docs.json)
• index.mdx (inferred from docs.json)
• api-reference/introduction.mdx (inferred from docs.json)

The navigation and sidebar structure for the documentation site is configured entirely within the docs.json file. This centralized approach allows for a declarative and hierarchical definition of all navigational elements, including top-level tabs, sidebar groups, page links, and the top navigation bar. The README.md file reinforces this by indicating that the development server should be run at the root where docs.json is located.

This configuration dictates the user's journey through the documentation, organizing content into logical sections like "Guides" and "API reference" and ensuring a consistent layout across the site.

Sources: docs.json, README.md:16-18

Core Navigation Structure

The primary navigation is controlled by the navigation object within docs.json. It uses a nested structure of tabs, groups, and pages to build the sidebar menu.

The diagram below illustrates the hierarchical relationship between these configuration elements.

Sources: docs.json:10-81

Tabs

Tabs are the highest level of organization, defined in the navigation.tabs array. Each object in this array creates a main tab on the documentation site, such as "Guides" and "API reference".

"tabs": [
  {
    "tab": "Guides",
    "groups": [ ... ]
  },
  {
    "tab": "API reference",
    "groups": [ ... ]
  }
]

Sources: docs.json:11-53, docs.json:54-80

Groups

Within each tab, groups are used to create collapsible sections in the sidebar. Each object in the groups array has a group name (the visible title) and a pages array.

Group Name	Parent Tab
Getting started	Guides
Customization	Guides
Writing content	Guides
AI tools	Guides
API documentation	API reference
Endpoint examples	API reference

Sources: docs.json:14-52, docs.json:57-79

Pages

The pages array within a group lists the actual content pages. The strings in this array correspond to the filenames of the markdown (.md or .mdx) files in the repository (without the extension). The order of strings in the array determines the order of pages in the sidebar.

For example, the "Getting started" group includes the following pages:

"pages": [
  "index",
  "quickstart",
  "development"
]

This configuration links to the index.mdx, quickstart.mdx, and development.mdx files.

Sources: docs.json:17-21, index.mdx, essentials/navigation.mdx

Top Navigation Bar (navbar)

The navbar object in docs.json configures the content of the sticky navigation bar at the top of the page. It consists of standard links and a primary call-to-action button.

Sources: docs.json:95-107

Navbar Links

The navbar.links array defines a list of standard hyperlink elements.

Property	Type	Description	Example Value
label	string	The text displayed for the link.	"Support"
href	string	The URL destination of the link.	"mailto:hi@mintlify.com"

Sources: docs.json:96-101

Primary Button

The navbar.primary object defines a styled call-to-action button, which is typically more prominent than the standard links.

Property	Type	Description	Example Value
type	string	The type of element, e.g., "button".	"button"
label	string	The text displayed on the button.	"Dashboard"
href	string	The URL destination of the button.	"https://dashboard.mintlify.com"

Sources: docs.json:102-106

Global Anchors

The global.anchors array is used to configure globally accessible links. These links appear as part of the main navigation structure and are accompanied by an icon.

Property	Type	Description	Example Value
anchor	string	The text label for the anchor link.	"Documentation"
href	string	The URL destination.	"https://mintlify.com/docs"
icon	string	The name of the icon to display.	"book-open-cover"

"global": {
  "anchors": [
    {
      "anchor": "Documentation",
      "href": "https://mintlify.com/docs",
      "icon": "book-open-cover"
    },
    {
      "anchor": "Blog",
      "href": "https://mintlify.com/blog",
      "icon": "newspaper"
    }
  ]
}

Sources: docs.json:82-93

API Reference Navigation

The navigation for the API reference section is also defined in docs.json under the "API reference" tab. It combines standard content pages with pages that document specific API endpoints.

The "API documentation" group contains introductory pages, while the "Endpoint examples" group links to pages detailing specific endpoints like GET, CREATE, and DELETE. The content for these endpoint pages is derived from the project's OpenAPI specification file.

Sources: docs.json:54-79, api-reference/openapi.json, api-reference/introduction.mdx