Navigation - Another Horizon

The navigation property in docs.json controls the structure and information hierarchy of your documentation. With proper navigation configuration, you can organize your content so that users can find exactly what they’re looking for. Choose one primary organizational pattern at the root level of your navigation. Once you’ve chosen your primary pattern, you can nest other navigation elements within it.

Pages

Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository.

In the navigation object, pages is an array where each entry must reference the path to a page file.

{
  "navigation": {
    "pages": [
      "settings",
      "pages",
      "navigation",
      "themes",
      "custom-domain"
    ]
  }
}

Groups

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

In the navigation object, groups is an array where each entry is an object that requires a group field and a pages field. The icon, tag, and expanded fields are optional.

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

Default expanded state

Use the expanded property to control the default state of a nested group in the navigation sidebar.

expanded: true: Group is expanded by default.
expanded: false or omitted: Group is collapsed by default.

The expanded property only affects nested groups—groups within groups. Top-level groups are always expanded and cannot be collapsed.

{
  "group": "Getting started",
  "pages": [
    "quickstart",
    {
      "group": "Advanced",
      "expanded": false,
      "pages": ["installation", "configuration"]
    }
  ]
}

Tabs

Tabs create distinct sections of your documentation with separate URL paths. Tabs create a horizontal navigation bar at the top of your documentation that lets users switch between sections.

In the navigation object, tabs is an array where each entry is an object that requires a tab field and can contain other navigation fields such as groups, pages, icons, or links to external pages.

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

Menus

Menus add dropdown navigation items to a tab. Use menus to help users go directly to specific pages within a tab. In the navigation object, menu is an array where each entry is an object that requires an item field and can contain other navigation fields such as groups, pages, icons, or links to external pages. Menu items can only contain groups, pages, and external links.

{
  "navigation": {
    "tabs": [
      {
        "tab": "Developer tools",
        "icon": "square-terminal",
        "menu": [
          {
            "item": "API reference",
            "icon": "rocket",
            "groups": [
              {
                "group": "Core endpoints",
                "icon": "square-terminal",
                "pages": [
                  "api-reference/get",
                  "api-reference/post",
                  "api-reference/delete"
                ]
              }
            ]
          },
          {
            "item": "SDKs",
            "icon": "code",
            "description": "SDKs are used to interact with the API.",
            "pages": [
              "sdk/fetch",
              "sdk/create",
              "sdk/delete"
            ]
          }
        ]
      }
    ]
  }
}

Anchors

Anchors add persistent navigation items to the top of your sidebar. Use anchors to section your content, provide quick access to external resources, or create prominent calls to action.

Decorative graphic of an anchor navigation.

In the navigation object, anchors is an array where each entry is an object that requires an anchor field and can contain other navigation fields such as groups, pages, icons, or links to external pages.

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

Global anchors

Use global anchors for external links that should appear on all pages, regardless of which section of your navigation the user is viewing. Global anchors are particularly useful for linking to resources outside your documentation, such as a blog, community forum, or support portal.

Global anchors must include an href field pointing to an external URL. They cannot contain relative paths.

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

Dropdowns

Dropdowns are contained in an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation.

Decorative graphic of a dropdown navigation.

In the navigation object, dropdowns is an array where each entry is an object that requires a dropdown field and can contain other navigation fields such as groups, pages, icons, or links to external pages.

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

Products

Products create a dedicated navigation division for organizing product-specific documentation. Use products to separate different offerings, services, or major feature sets within your documentation. In the navigation object, products is an array where each entry is an object that requires a product field and can contain other navigation fields such as groups, pages, icons, or links to external pages.

{
  "navigation": {
    "products": [
      {
        "product": "Core API",
        "description": "Core API description",    
        "icon": "api",
        "groups": [
          {
            "group": "Getting started",
            "pages": [
              "core-api/quickstart",
              "core-api/authentication"
            ]
          },
          {
            "group": "Endpoints",
            "pages": [
              "core-api/users",
              "core-api/orders"
            ]
          }
        ]
      },
      {
        "product": "Analytics Platform",
        "description": "Analytics Platform description",
        "icon": "chart-bar",
        "pages": [
          "analytics/overview",
          "analytics/dashboard",
          "analytics/reports"
        ]
      },
      {
        "product": "Mobile SDK",
        "description": "Mobile SDK description",
        "icon": "smartphone",
        "href": "https://mobile-sdk-docs.example.com"
      }
    ]
  }
}

OpenAPI

Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components. Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.

When you add the openapi property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for all endpoints defined in your OpenAPI specification.To control which endpoints appear, explicitly list the desired endpoints in a pages array.

For more information about referencing OpenAPI endpoints in your docs, see the OpenAPI setup.

{
  "navigation": {
    "groups": [
      {
        "group": "API reference",
        "openapi": "/path/to/openapi-v1.json",
        "pages": [
          "overview",
          "authentication",
          "GET /users",
          "POST /users",
          {
            "group": "Products",
            "openapi": "/path/to/openapi-v2.json",
            "pages": [
              "GET /products",
              "POST /products"
            ]
          }
        ]
      }
    ]
  }
}

Versions

Partition your navigation into different versions. Versions are selectable from a dropdown menu.

In the navigation object, versions is an array where each entry is an object that requires a version field and can contain any other navigation fields.

{
  "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

Partition your navigation into different languages. Languages are selectable from a dropdown menu.

In the navigation object, languages is an array where each entry is an object that requires a language field and can contain any other navigation fields, including language-specific banner configurations. We currently support the following languages for localization:

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/ar.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=1d2b397bae3100c21089394967d5b6ed

Arabic (ar)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/cs.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=bcdcc7105aa807745d5a6e5995143b2d

Czech (cs)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/cn.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=99c00d04cf00d95d817243e86caee8ff

Chinese (cn)

Chinese (zh-Hant)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/nl.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=ce46a9dda6d7392480f7ce4075e188df

Dutch (nl)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/en.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=b151ddb015628c19c00932810eab6cf5

English (en)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/fr.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=0c08d85a6310af694c8e3d9de22dd77b

French (fr)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/de.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=f91331daba7fb3a197871d65ed38d135

German (de)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/he.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=0f8fd0220d50d6dc29334681881436b8

Hebrew (he)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/hi.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=da4adc3507f2e358bcf52ce3406a87c4

Hindi (hi)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/id.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=f9d62873a61be465cd00517a1f3d3b77

Indonesian (id)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/it.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=6bc84439d7708f6e749bdc5cb8e53076

Italian (it)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/jp.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=bf989858bb84d8e530256f1dfd79e172

Japanese (jp)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/ko.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=6ac5841deffd49b6f0e4f3dd344483ce

Korean (ko)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/lv.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=2156d30e10212a2849d9402ea28b9aae

Latvian (lv)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/no.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=daffdef00e4c2f4ce37bddfc1c0b1923

Norwegian (no)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/pl.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=381ea98b6166475b88dc7d54d19b4456

Polish (pl)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/pt-br.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=b7184110f9c80dd41a7e464eba0a3a8e

Portuguese (pt-BR)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/ro.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=551adefac53399decf0fc342be780387

Romanian (ro)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/ru.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=6613ba259835e368403641ae3fea58ea

Russian (ru)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/es.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=4ea8c27c82f881483942a652a6e948c1

Spanish (es)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/sv.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=a8067feb17d3b6a9503762fadf5b5b9c

Swedish (sv)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/tr.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=68b9d91330437a1783d0873e91d145e3

Turkish (tr)

https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/navigation/languages/ua.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=a8c8c36fe3ac2153f78cb6bfe9a002a0

Ukrainian (ua)

https://mintcdn.com/anotherhorizon/KtT4EXjd_91dkOA7/images/navigation/languages/uz.png?fit=max&auto=format&n=KtT4EXjd_91dkOA7&q=85&s=87098bb08e3f7a6fae5709204315d91c

Uzbek (uz)

https://mintcdn.com/anotherhorizon/KtT4EXjd_91dkOA7/images/navigation/languages/vi.png?fit=max&auto=format&n=KtT4EXjd_91dkOA7&q=85&s=d1102f0e3eab69b9d759b2384dd57b1f

Vietnamese (vi)

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "banner": {
          "content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["en/overview", "en/quickstart", "en/development"]
          }
        ]
      },
      {
        "language": "es",
        "banner": {
          "content": "🚀 ¡La versión 2.0 ya está disponible! Consulta nuestro [registro de cambios](/es/changelog).",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["es/overview", "es/quickstart", "es/development"]
          }
        ]
      }
    ]
  }
}

For automated translations, contact our sales team to discuss solutions.

Nesting

Navigation elements can be nested within each other to create complex hierarchies. You must have one root-level parent navigation element such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern. Each navigation element can contain one type of child element at each level of your navigation hierarchy. For example, a tab can contain anchors that contain groups, but a tab cannot contain both anchors and groups at the same level.

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "anchors": [
          {
            "anchor": "Guides",
            "icon": "book-open",
            "pages": ["quickstart", "tutorial"]
          },
          {
            "anchor": "API Reference",
            "icon": "code",
            "pages": ["api/overview", "api/endpoints"]
          }
        ]
      },
      {
        "tab": "Resources",
        "groups": [
          {
            "group": "Help",
            "pages": ["support", "faq"]
          }
        ]
      }
    ]
  }
}

Breadcrumbs

Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs are enabled for your site using the styling property in your docs.json.

"styling": {
  "eyebrows": "breadcrumbs"
}

Interaction configuration

Control how users interact with navigation elements using the interaction property in your docs.json. When a user expands a navigation group, some themes will automatically navigate to the first page in the group. You can override a theme’s default behavior using the drilldown option.

Set to true to force automatic navigation to the first page when a navigation group is selected.
Set to false to prevent navigation and only expand or collapse the group when it is selected.
Leave unset to use the theme’s default behavior.

"interaction": {
  "drilldown": true  // Force navigation to first page when a user expands a dropdown
}

Get started

Organize

Customize

Create content

Document APIs

Deploy

Optimize

​Pages

​Groups

​Default expanded state

​Tabs

​Menus

​Anchors

​Global anchors

​Dropdowns

​Products

​OpenAPI

​Versions

​Languages

Arabic (ar)

Czech (cs)

Chinese (cn)

Chinese (zh-Hant)

Dutch (nl)

English (en)

French (fr)

German (de)

Hebrew (he)

Hindi (hi)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Latvian (lv)

Norwegian (no)

Polish (pl)

Portuguese (pt-BR)

Romanian (ro)

Russian (ru)

Spanish (es)

Swedish (sv)

Turkish (tr)

Ukrainian (ua)

Uzbek (uz)

Vietnamese (vi)

​Nesting

​Breadcrumbs

​Interaction configuration

​Enable auto-navigation for groups

Pages

Groups

Default expanded state

Tabs

Menus

Anchors

Global anchors

Dropdowns

Products

OpenAPI

Versions

Languages

Nesting

Breadcrumbs

Interaction configuration

Enable auto-navigation for groups