Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
259 changes: 259 additions & 0 deletions organize/navigation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -98,11 +98,11 @@

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

- `expanded: true`: Group is expanded by default.

Check warning on line 101 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L101

In general, use active voice instead of passive voice ('is expanded').
- `expanded: false` or omitted: Group is collapsed by default.

Check warning on line 102 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L102

In general, use active voice instead of passive voice ('is collapsed').

<Note>
The `expanded` property only affects nested groups--groups within groups. Top-level groups are always expanded and cannot be collapsed.

Check warning on line 105 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L105

Use 'can't' instead of 'cannot'.

Check warning on line 105 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L105

In general, use active voice instead of passive voice ('be collapsed').
</Note>

```json
Expand All @@ -119,6 +119,265 @@
}
```

### Tags and labels

Use tags to highlight navigation groups with status indicators or labels. Tags appear as small badges next to group names in the sidebar, helping users identify new features, beta functionality, deprecated content, or other important states.

Check warning on line 124 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L124

Use 'capability' or 'feature' instead of 'functionality'.

Tags are particularly useful for:
- Announcing new features or sections
- Indicating beta or experimental functionality

Check warning on line 128 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L128

Use 'capability' or 'feature' instead of 'functionality'.
- Marking deprecated content
- Highlighting premium or enterprise features
- Drawing attention to recently updated sections

#### Adding tags to groups

Add a `tag` field to any navigation group. The tag text appears as a badge next to the group name.

```json
{
"navigation": {
"groups": [
{
"group": "AI Features",
"icon": "sparkles",
"tag": "NEW",
"pages": ["ai/overview", "ai/chat", "ai/embeddings"]
},
{
"group": "Experimental APIs",
"icon": "flask",
"tag": "BETA",
"pages": ["experimental/streaming", "experimental/webhooks"]
},
{
"group": "Legacy SDK",
"icon": "box-archive",
"tag": "DEPRECATED",
"pages": ["legacy/v1", "legacy/migration"]
}
]
}
}
```

#### Tags with nested groups

Tags work with nested groups at any level of your navigation hierarchy. Each group can have its own tag.

```json
{
"navigation": {
"groups": [
{
"group": "API Reference",
"icon": "code",
"pages": [
"api/overview",
{
"group": "REST API",
"tag": "STABLE",
"pages": ["api/rest/users", "api/rest/projects"]
},
{
"group": "GraphQL API",
"tag": "BETA",
"pages": ["api/graphql/queries", "api/graphql/mutations"]
},
{
"group": "SOAP API",
"tag": "DEPRECATED",
"pages": ["api/soap/overview"]
}
]
}
]
}
}
```

#### Tags with tabs

Add tags to tabs to highlight entire sections of your documentation.

```json
{
"navigation": {
"tabs": [
{
"tab": "Documentation",
"icon": "book-open",
"pages": ["quickstart", "guides"]
},
{
"tab": "API Reference",
"icon": "code",
"tag": "v2.0",
"groups": [
{
"group": "Endpoints",
"pages": ["api/users", "api/projects"]
}
]
},
{
"tab": "Mobile SDK",
"icon": "mobile",
"tag": "PREVIEW",
"pages": ["mobile/ios", "mobile/android"]
}
]
}
}
```

#### Tags with anchors

Use tags on anchors to draw attention to specific sections in your sidebar navigation.

```json
{
"navigation": {
"anchors": [
{
"anchor": "Documentation",
"icon": "book-open",
"pages": ["quickstart", "guides"]
},
{
"anchor": "API v2",
"icon": "code",
"tag": "NEW",
"pages": ["api/overview", "api/endpoints"]
},
{
"anchor": "Community",
"icon": "users",
"tag": "BETA",
"href": "https://community.example.com"
}
]
}
}
```

#### Best practices for tags

**Keep tags concise.** Use short, clear labels that fit comfortably next to group names. Ideal tags are 3-10 characters.

**Use consistent terminology.** Establish a standard set of tags across your documentation:
- `NEW` - Recently added features or sections
- `BETA` - Features in beta testing
- `PREVIEW` - Early access features
- `DEPRECATED` - Features being phased out

Check warning on line 272 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L272

In general, use active voice instead of passive voice ('being phased').
- `UPDATED` - Recently updated content
- `PRO` or `ENTERPRISE` - Premium features

**Use tags sparingly.** Too many tags reduce their effectiveness. Reserve tags for truly important status indicators.

**Update tags regularly.** Remove `NEW` tags after features become established. Update `BETA` tags when features reach general availability.

**Consider your audience.** Use tags that provide value to your users. Version numbers (`v2.0`) work well for API documentation, while status indicators (`BETA`) work better for feature documentation.

Check warning on line 280 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L280

Use parentheses judiciously.

#### Common tag examples

<CodeGroup>

```json Feature status
{
"groups": [
{
"group": "Core Features",
"tag": "STABLE",
"pages": ["features/auth", "features/storage"]
},
{
"group": "Advanced Features",
"tag": "NEW",
"pages": ["features/ai", "features/analytics"]
},
{
"group": "Experimental",
"tag": "BETA",
"pages": ["features/realtime", "features/edge"]
}
]
}
```

```json Version indicators
{
"groups": [
{
"group": "API v3",
"tag": "LATEST",
"pages": ["v3/overview", "v3/endpoints"]
},
{
"group": "API v2",
"tag": "v2.5",
"pages": ["v2/overview", "v2/endpoints"]
},
{
"group": "API v1",
"tag": "EOL 2026",
"pages": ["v1/overview", "v1/migration"]
}
]
}
```

```json Access levels
{
"groups": [
{
"group": "Free Features",
"pages": ["free/basics", "free/limits"]
},
{
"group": "Pro Features",
"tag": "PRO",
"pages": ["pro/advanced", "pro/analytics"]
},
{
"group": "Enterprise Features",
"tag": "ENTERPRISE",
"pages": ["enterprise/sso", "enterprise/audit"]
}
]
}
```

```json Update notifications
{
"groups": [
{
"group": "Getting Started",
"pages": ["quickstart", "installation"]
},
{
"group": "Authentication",
"tag": "UPDATED",
"pages": ["auth/oauth", "auth/jwt", "auth/api-keys"]
},
{
"group": "Deployment",
"pages": ["deploy/cloud", "deploy/self-hosted"]
}
]
}
```

</CodeGroup>

#### Styling considerations

Tags inherit your documentation's color scheme and automatically adapt to light and dark modes. The tag appearance is determined by your theme selection in `docs.json`.

Check warning on line 375 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L375

In general, use active voice instead of passive voice ('is determined').

Tags are designed to be visually distinct without overwhelming the navigation. They use subtle styling that complements your theme's design while remaining clearly visible.

Check warning on line 377 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L377

In general, use active voice instead of passive voice ('are designed').

For consistent branding across your documentation, use the same tag terminology in your page content when referring to tagged features. For example, if you tag a group as `BETA`, mention the beta status in the corresponding pages.

## 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.
Expand Down Expand Up @@ -271,7 +530,7 @@
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.

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

Check warning on line 533 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L533

Use 'can't' instead of 'cannot'.
</Note>

```json
Expand All @@ -298,7 +557,7 @@

## 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.

Check warning on line 560 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L560

In general, use active voice instead of passive voice ('are contained').

<img
className="block dark:hidden pointer-events-none"
Expand Down Expand Up @@ -413,10 +672,10 @@

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.

Check warning on line 675 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L675

Avoid using 'will'.

<Note>
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.

Check warning on line 678 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L678

Use parentheses judiciously.

To control which endpoints appear, explicitly list the desired endpoints in a `pages` array.
</Note>
Expand Down Expand Up @@ -513,7 +772,7 @@

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.

We currently support the following languages for localization:

Check warning on line 775 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L775

Try to avoid using first-person plural like 'We'.

<CardGroup cols={2}>
<Card title="Arabic (ar)" icon="/images/navigation/languages/ar.png" horizontal />
Expand Down Expand Up @@ -575,9 +834,9 @@

## 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.

Check warning on line 837 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L837

In general, use active voice instead of passive voice ('be nested').

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.

Check warning on line 839 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L839

Use 'can't' instead of 'cannot'.

<CodeGroup>

Expand Down Expand Up @@ -799,7 +1058,7 @@

## 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`.

Check warning on line 1061 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1061

Use 'don't' instead of 'do not'.

Check warning on line 1061 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1061

In general, use active voice instead of passive voice ('are enabled').

<CodeGroup>

Expand All @@ -823,10 +1082,10 @@

### Enable auto-navigation for groups

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.

Check warning on line 1085 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1085

Avoid using 'will'.

- Set to `true` to force automatic navigation to the first page when a navigation group is selected.

Check warning on line 1087 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1087

In general, use active voice instead of passive voice ('is selected').
- Set to `false` to prevent navigation and only expand or collapse the group when it is selected.

Check warning on line 1088 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1088

Use 'it's' instead of 'it is'.

Check warning on line 1088 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1088

In general, use active voice instead of passive voice ('is selected').
- Leave unset to use the theme's default behavior.

<CodeGroup>
Expand Down