Revamping a navigation schema might not sound flashy, but shipping docs.json is a major foundational update to mintlify.

Our original mint.json worked well early on, but as we introduced features like anchors and tabs, managing navigation became increasingly complex for our users. Logic spread across versions, anchors, and tabs made it harder to maintain and predict navigation behavior.

With docs.json, we've refactored every piece of our codebase to make it simpler and more intuitive for customers to define navigation.

Read on to understand what's changed.

In the mint.json, the navigation was defined by both the navigation field AND the tabs, anchors, and versions fields. All these fields were related to each other and had to be mapped together.

In the docs.json, the navigation is solely defined by the navigation field.

For example, here is a mint.json file:

{
  "tabs": [
    {
      "name": "Components",
      "url": "content"
    },
    {
      "name": "Integrations",
      "url": "integrations"
    }
  ],
  "navigation": [
    {
      "group": "Components",
      "pages": [
        "content/components/accordions",
        "content/components/accordion-groups",
        "content/components/callouts"
      ]
    },
    {
      "group": "API Components",
      "pages": ["content/components/params", "content/components/responses"]
    },
    {
      "group": "Analytics",
      "pages": [
        "integrations/analytics/overview",
        "integrations/analytics/amplitude",
        "integrations/analytics/clearbit"
      ]
    },
    {
      "group": "SDKs",
      "pages": ["integrations/sdks/providers", "integrations/sdks/clients"]
    }
  ]
}

And its equivalent docs.json file: 

{
  "navigation": {
    "tabs": [{
      "tab": "Components",
      "groups": [
        {
          "group": "Components",
          "pages": [
            "content/components/accordions",
            "content/components/accordion-groups",
            "content/components/callouts",
            ...
          ]
        },
        {
          "group": "API Components",
          "pages": [
            "content/components/params",
            "content/components/responses",
            ...
          ]
        }
      ]
    },
    {
      "tab": "Integrations",
      "groups": [
        {
          "group": "Analytics",
          "pages": [
            "integrations/analytics/overview",
            "integrations/analytics/amplitude",
            "integrations/analytics/clearbit",
            ...
          ]
        },
        {
          "group": "SDKs",
          "pages": ["integrations/sdks/providers", "integrations/sdks/clients"]
        }
      ]
    }]
  }
}

In the above mint.json example, the navigation is one combined array of groups and the tabs are a separate array. The tabs serve to group the groups in the navigation. This isn't very intuitive and it's hard to manage.

In the docs.json there is no separation between tabs, groups, and pages - they are integrated into one large recursive structure. So it is very obvious how the groups are grouped into tabs.

Tabs and anchors are no longer restricted to a single folder of the same name. Previously with mint.json a tab had to correlate with a folder in the file tree. Now you can have a tab with an assortment of files in different folders.

Example docs.json 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"
            ]
          }
        ]
      }
    ]
  }
}

All the benefits we've been discussing with tabs is applicable for versions, anchors, languages, and dropdowns. And you can now arbitrarily mix and nest any combination of these divisions.

This gives a lot of freedom for you to pick and choose the hierarchy you want - either tabs or anchors can be on the highest level.

Here is a complex example that includes all the different types of divisions - versions, anchors, languages, and dropdowns. Now you can have versions applied to only a specific tab and reference tabs at one layer and then reference them again further down the hierarchy.

Example docs.json file:

{
  "languages": [
    {
      "language": "en",
      "tabs": [
        {
          "tab": "Guides",
          "pages": ["en/overview", "en/quickstart"]
        },
        {
          "tab": "SDKs",
          "versions": [
            {
              "version": "latest",
              "anchors": [
                {
                  "anchor": "Javascript",
                  "pages": ["en/sdk/js/create", "en/sdk/js/edit", "en/sdk/js/delete"]
                },
                {
                  "anchor": "Python",
                  "pages": ["en/sdk/py/create", "en/sdk/py/edit", "en/sdk/py/delete"]
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "language": "es",
      "tabs": [
        {
          "tab": "Guías",
          "pages": ["es/overview", "es/quickstart"]
        },
        {
          "tab": "SDKs",
          "versions": [
            {
              "version": "último",
              "anchors": [
                {
                  "anchor": "Javascript",
                  "pages": ["es/sdk/js/create", "es/sdk/js/edit", "es/sdk/js/delete"]
                },
                {
                  "anchor": "Python",
                  "pages": ["es/sdk/py/create", "es/sdk/py/edit", "es/sdk/py/delete"]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Please upgrade your CLI to the latest version.

1. Make sure your CLI is the latest version: 

‍npm i mintlify@latest -g

2. In your docs repository, run

‍mintlify upgrade

3. Delete your old mint.json and push your changes