Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sorgm/data-architecture-docs/llms.txt

Use this file to discover all available pages before exploring further.

The navigation structure in docs.json defines how users browse your documentation. You’ll update this field every time you add a new page, as pages don’t appear automatically. Navigation in Mintlify is hierarchical with three levels: tabs, groups, and pages. 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart", "development"]
          }
        ]
      }
    ]
  }
}
You don’t need to include .mdx file extensions in page names. Mintlify automatically resolves them.

​
Tabs

Tabs are top-level navigation sections that appear horizontally at the top of your sidebar. Use tabs to separate major areas of your documentation. 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [...]
      }
    ]
  }
}
Common tab patterns:
  • Guides - Tutorials and how-to documentation
  • API Reference - API endpoint documentation
  • Examples - Code examples and use cases
  • Resources - Additional materials and references

​
Groups

Groups organize related pages within a tab. Each group displays as a collapsible section in the sidebar. 
{
  "tab": "Guides",
  "groups": [
    {
      "group": "Getting started",
      "pages": ["index", "quickstart", "development"]
    },
    {
      "group": "Customization",
      "pages": ["essentials/settings", "essentials/navigation"]
    },
    {
      "group": "Writing content",
      "pages": ["essentials/markdown", "essentials/code", "essentials/images"]
    }
  ]
}
Group names should be concise and descriptive. They help users quickly scan and find relevant content.

​
Pages

Pages are individual MDX files in your documentation. Reference them by their path relative to your project root.

​
Basic Page References

{
  "group": "Getting started",
  "pages": [
    "index",
    "quickstart",
    "development"
  ]
}

​
Pages in Folders

Organize pages into folders and reference them with folder paths. 
{
  "group": "Customization",
  "pages": [
    "essentials/settings",
    "essentials/navigation",
    "essentials/markdown"
  ]
}
For a page at https://yoursite.com/essentials/settings, create a file at essentials/settings.mdx.
You cannot use api as a top-level folder name. Next.js reserves this for internal server calls. Use names like api-reference instead, or nest it inside another folder.

​
Nested Navigation

Create nested groups for complex documentation structures. This is useful for detailed API references or multi-level guides. 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              "quickstart",
              {
                "group": "Advanced Setup",
                "pages": [
                  "advanced/configuration",
                  "advanced/deployment"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

{
  "navigation": {
    "tabs": [
      {
        "tab": "API reference",
        "groups": [
          {
            "group": "Endpoints",
            "pages": [
              "api-reference/introduction",
              {
                "group": "User Management",
                "pages": [
                  "api-reference/users/list",
                  "api-reference/users/create",
                  {
                    "group": "User Permissions",
                    "pages": [
                      "api-reference/users/permissions/list",
                      "api-reference/users/permissions/update"
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

​
Documentation with API Reference

A common pattern separates conceptual guides from API documentation. 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart", "development"]
          },
          {
            "group": "Customization",
            "pages": ["essentials/settings", "essentials/navigation"]
          }
        ]
      },
      {
        "tab": "API reference",
        "groups": [
          {
            "group": "API documentation",
            "pages": ["api-reference/introduction"]
          },
          {
            "group": "Endpoint examples",
            "pages": [
              "api-reference/endpoint/get",
              "api-reference/endpoint/create",
              "api-reference/endpoint/delete"
            ]
          }
        ]
      }
    ]
  }
}

​
Product Documentation

For product docs, organize by user journey or feature area. 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["introduction", "installation", "authentication"]
          },
          {
            "group": "Core features",
            "pages": ["features/workspaces", "features/collaboration", "features/integrations"]
          },
          {
            "group": "Advanced",
            "pages": ["advanced/security", "advanced/performance", "advanced/customization"]
          },
          {
            "group": "Support",
            "pages": ["troubleshooting", "faq", "contact"]
          }
        ]
      }
    ]
  }
}

​
Multi-Product Documentation

For companies with multiple products, use tabs to separate each product. 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Platform",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["platform/introduction", "platform/quickstart"]
          }
        ]
      },
      {
        "tab": "Analytics",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["analytics/introduction", "analytics/quickstart"]
          }
        ]
      },
      {
        "tab": "SDK",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["sdk/introduction", "sdk/installation"]
          }
        ]
      }
    ]
  }
}

​
Hidden Pages

MDX files not included in docs.json won’t appear in the sidebar but remain accessible through:
  • Search bar results
  • Direct URL links
  • Internal page links
This is useful for:
  • Draft pages you’re still working on
  • Auxiliary pages linked from main content
  • Pages you want discoverable but not prominent

​
Global Anchors

Add permanent navigation anchors that appear above tabs for important external links. 
{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "Documentation",
          "href": "https://mintlify.com/docs",
          "icon": "book-open-cover"
        },
        {
          "anchor": "Blog",
          "href": "https://mintlify.com/blog",
          "icon": "newspaper"
        }
      ]
    },
    "tabs": [...]
  }
}

​
Complete Example

Here’s a fully configured navigation structure demonstrating all concepts: 
{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "Documentation",
          "href": "https://mintlify.com/docs",
          "icon": "book-open-cover"
        }
      ]
    },
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart", "development"]
          },
          {
            "group": "Customization",
            "pages": ["essentials/settings", "essentials/navigation"]
          },
          {
            "group": "Writing content",
            "pages": [
              "essentials/markdown",
              "essentials/code",
              "essentials/images",
              "essentials/reusable-snippets"
            ]
          },
          {
            "group": "AI tools",
            "pages": ["ai-tools/cursor", "ai-tools/claude-code", "ai-tools/windsurf"]
          }
        ]
      },
      {
        "tab": "API reference",
        "groups": [
          {
            "group": "API documentation",
            "pages": ["api-reference/introduction"]
          },
          {
            "group": "Endpoint examples",
            "pages": [
              "api-reference/endpoint/get",
              "api-reference/endpoint/create",
              "api-reference/endpoint/delete",
              "api-reference/endpoint/webhook"
            ]
          }
        ]
      }
    ]
  }
}

​
Best Practices

Logical Grouping

Group related pages together. Users should intuitively know where to find information.

Consistent Naming

Use consistent naming conventions across groups and pages for better scannability.

Shallow Hierarchies

Avoid deep nesting. Keep navigation 2-3 levels deep for best user experience.

Clear Labels

Use descriptive, concise labels. Avoid jargon unless your audience expects it.

​
Next Steps

Settings

Customize your site’s appearance and configuration

Markdown

Learn Mintlify’s markdown syntax and components

Build docs developers (and LLMs) love

Get started for freeTalk to us