Navigation

The navigation property in docs.json defines how users will browse through your documentation. Think of it as the blueprint for your documentation’s menu structure. With proper navigation configuration, you can organize your content into a logical hierarchy that makes it easy for users to find exactly what they’re looking for.

Do not use api as a title for any navigation element. The /api path is reserved in production and will cause pages to return 404 errors if their URLs contain /api.

Pages

Pages are the most fundamental navigation component.

Pages is an array where each entry must be a reference to the path of a page file.

{
  "navigation": {
    "pages": [
      "overview",
      "quickstart",
      "advanced/components",
      "advanced/integrations"
    ]
  }
}

Groups

Use groups to organize your navigation into sections. Groups can be nested within each other, labeled with tags, and styled with icons.

{
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
		"icon": "play",
        "pages": [
          "quickstart",
          {
            "group": "Editing",
			"icon": "pencil",
            "pages": [
				"installation",
				"editor",
				{
					"group": "Nested group",
					"icon": "code",
					"pages": [
						"navigation",
						"code"
					]
				}
			]
          }
        ]
      },
      {
        "group": "Writing Content",
 		"icon": "notebook-text",
        "tag": "NEW",
        "pages": ["writing-content/page", "writing-content/text"]
      }
    ]
  }
}

Tabs

Tabs help distinguish between different topics or sections of your documentation.

"navigation": {
  "tabs": [
    {
      "tab": "API References",
      "pages": [
        "api-reference/get",
        "api-reference/post",
        "api-reference/delete"
      ]
    },
    {
      "tab": "SDKs",
      "pages": [
        "sdk/fetch",
        "sdk/create",
        "sdk/delete",
      ]
    },
    {
      "tab": "Blog",
      "href": "https://external-link.com/blog"
    }
  ]
}

Anchors

Anchors are another way to section your content. They show up on top of your side navigation.

The configuration is very similar to tabs. While not required, we highly recommend that you set an icon field as well.

"navigation": {
  "anchors": [
    {
      "anchor": "Documentation",
      "icon": "book-open",
      "pages": [
        "quickstart",
        "development",
        "navigation"
      ]
    },
    {
      "anchor": "API References",
      "icon": "square-terminal",
      "pages": [
        "api-reference/get",
        "api-reference/post",
        "api-reference/delete"
      ]
    },
    {
      "anchor": "Blog",
      "href": "https://external-link.com/blog"
    }
  ]
}

Anchors that strictly contain external links can be achieved using the global keyword:

"navigation": {
  "global":  {
    "anchors": [
      {
         "anchor": "Community",
         "icon": "house",
         "href": "https://slack.com"
      },
      {
         "anchor": "Blog",
         "icon": "pencil",
         "href": "https://mintlify.com/blog"
      }
    ]
  },
  "tabs": /*...*/
}

Dropdowns

Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown.

While not required, we also recommend that you set an icon for each dropdown item.

"navigation": {
  "dropdowns": [
    {
      "dropdown": "Documentation",
      "icon": "book-open",
      "pages": [
        "quickstart",
        "development",
        "navigation"
      ]
    }
    {
      "dropdown": "API References",
      "icon": "square-terminal",
      "pages": [
        "api-reference/get",
        "api-reference/post",
        "api-reference/delete"
      ]
    }
    {
      "dropdown": "Blog",
      "href": "https://external-link.com/blog"
    }
  ]
}

Versions

Versions can be leveraged to partition your navigation into different versions.

{
  "navigation": {
    "versions": [
      {
        "version": "1.0.0",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["v1/overview", "v1/quickstart", "v1/development"]
          }
        ]
      },
      {
        "version": "2.0.0",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["v2/overview", "v2/quickstart", "v2/development"]
          }
        ]
      }
    ]
  }
}

Languages

Languages can be leveraged to partition your navigation into different languages.

You can automate translations of your documentation into any supported language.

We currently support the following languages:

Arabic (ar)

Chinese (cn)

Chinese (zh-Hant)

English (en)

French (fr)

German (de)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Portuguese (pt)

Portuguese (pt-BR)

Russian (ru)

Spanish (es)

Turkish (tr)

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["en/overview", "en/quickstart", "en/development"]
          }
        ]
      },
      {
        "language": "es",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["es/overview", "es/quickstart", "es/development"]
          }
        ]
      }
    ]
  }
}

Nesting

It’s important to note that you can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably. This way, you can create a very complex navigation structure that is easy to manage.

{
  "navigation": {
    "anchors": [
      {
        "anchor": "Anchor 1",
        "groups": [
          {
            "group": "Group 1",
            "pages": [
              "some-folder/file-1",
              "another-folder/file-2"
              "just-a-file"
            ]
          }
        ]
      }
      {
        "anchor": "Anchor 2",
        "groups": [
          {
            "group": "Group 2",
            "pages": [
              "some-other-folder/file-1",
              "various-different-folders/file-2",
              "another-file"
            ]
          }
        ]
      }
    ]
  }
}

{
  "navigation": {
    "tabs": [
      {
        "tab": "Tab 1",
        "groups": [
          {
            "group": "Group 1",
            "pages": [
              "some-folder/file-1",
              "another-folder/file-2"
              "just-a-file"
            ]
          }
        ]
      }
      {
        "tab": "Tab 2",
        "groups": [
          {
            "group": "Group 2",
            "pages": [
              "some-other-folder/file-1",
              "various-different-folders/file-2",
              "another-file"
            ]
          }
        ]
      }
    ]
  }
}

{
  "navigation": {
    "tabs": [
      {
        "tab": "Tab 1",
        "global": {
          "anchors": [
            {
              "anchor": "Anchor 1",
              "href": "https://mintlify.com/docs"
            }
          ]
        },
        "groups": [
          {
            "group": "Group 1",
            "pages": [
              "some-folder/file-1",
              "another-folder/file-2"
              "just-a-file"
            ]
          }
        ]
      }
      {
        "tab": "Tab 2",
        "groups": [
          {
            "group": "Group 2",
            "pages": [
              "some-other-folder/file-1",
              "various-different-folders/file-2",
              "another-file"
            ]
          }
        ]
      }
    ]
  }
}

Getting started

Core configuration

Components

API pages

Authentication and personalization

Guides

Integrations

Version control and CI/CD

Pages

Groups

Tabs

Anchors

Dropdowns

Versions

Languages

Arabic (ar)

Chinese (cn)

Chinese (zh-Hant)

English (en)

French (fr)

German (de)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Portuguese (pt)

Portuguese (pt-BR)

Russian (ru)

Spanish (es)

Turkish (tr)

Nesting

​Pages

​Groups

​Tabs

​Anchors

​Dropdowns

​Versions

​Languages

Arabic (ar)

Chinese (cn)

Chinese (zh-Hant)

English (en)

French (fr)

German (de)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Portuguese (pt)

Portuguese (pt-BR)

Russian (ru)

Spanish (es)

Turkish (tr)

​Nesting

Pages

Groups

Tabs

Anchors

Dropdowns

Versions

Languages

Nesting