Skip to main content
The navigation in 通用文档站点 is defined entirely in docs.json and controls the sidebar your users see when they visit your site. Every page you want to surface must be listed in this configuration — if a page is missing from docs.json, it will not appear in the sidebar, even if the file exists on disk.

​
Navigation structure

通用文档站点 navigation is organized across three levels, from broadest to most specific:
  • Tabs — top-level sections that appear in the main navigation bar, useful for separating major areas like “Documentation” and “API Reference”
  • Groups — named sections within a tab that cluster related pages together in the sidebar
  • Pages — individual MDX files listed inside a group, referenced by their path relative to the docs root
Here is a complete example using tabs:
docs.json
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Get Started",
          "pages": ["introduction", "quickstart"]
        }
      ]
    }
  ]
}

​
Using groups only

For simpler sites that do not need top-level tabs, you can skip the tabs layer and define groups directly under navigation. This keeps the structure flat and is a good fit for documentation that covers a single product area.
docs.json
"navigation": {
  "groups": [
    { "group": "Get Started", "pages": ["introduction"] }
  ]
}

​
Page paths

Page paths in docs.json are relative to your docs root and do not include the .mdx file extension. For example, a file located at guides/content.mdx is referenced in navigation as "guides/content".
File pathNavigation entry
introduction.mdx"introduction"
guides/content.mdx"guides/content"
api/authentication.mdx"api/authentication"

​
Sidebar titles

By default, 通用文档站点 uses the title from a page’s frontmatter as the label in the sidebar. For pages with long titles, you can override this with the sidebarTitle frontmatter field to display a shorter label without changing the page title itself. 
---
title: "Writing content with Markdown and MDX"
sidebarTitle: "Writing Content"
---
In this example, the page heading reads “Writing content with Markdown and MDX”, but the sidebar shows the shorter label “Writing Content”, keeping your navigation easy to scan.
Every page listed in your navigation must have a corresponding .mdx file. If a file is missing, validation will fail and your site will not build. Run mint validate to check for missing files before deploying.
Aim for 15–25 total pages in your navigation for the best readability. If your docs are growing beyond that, consider splitting content across multiple tabs or using a separate docs product for distinct subject areas.