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
98 changes: 98 additions & 0 deletions navigation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,10 @@
{
"navigation": {
"pages": [
"settings",

Check warning on line 33 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L33

Commas and periods go inside quotation marks.
"pages",

Check warning on line 34 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L34

Commas and periods go inside quotation marks.
"navigation",

Check warning on line 35 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L35

Commas and periods go inside quotation marks.
"themes",

Check warning on line 36 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L36

Commas and periods go inside quotation marks.
"custom-domain"
]
}
Expand Down Expand Up @@ -247,9 +247,9 @@
}
```

For anchors that direct to external links only, use the `global` keyword. Anchors in a `global` object must have an `href` field and cannot point to a relative path.

Check warning on line 250 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L250

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

Global anchors are particularly useful for linking to resources that are not part of your documentation, but should be readily accessible to your users like a blog or support portal

Check warning on line 252 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L252

Use 'aren't' instead of 'are not'.

```json
{
Expand All @@ -275,7 +275,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 278 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L278

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

<img
className="block dark:hidden pointer-events-none"
Expand Down Expand Up @@ -324,7 +324,7 @@

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 327 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L327

Avoid using 'will'.

```json
{
Expand Down Expand Up @@ -414,7 +414,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 417 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L417

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

<CardGroup cols={2}>
<Card title="Arabic (ar)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/ar.png" className="w-6 h-6 my-0" />} horizontal />
Expand Down Expand Up @@ -462,9 +462,107 @@

For automated translations, [contact our sales team](mailto:[email protected]) to discuss solutions.

## Combining navigation types

You can combine different navigation types to create sophisticated documentation structures that match your content organization needs. Each navigation type serves different purposes and can be strategically combined for optimal user experience.

### Common combinations

**Tabs with groups and pages** - Use tabs to separate major sections, groups to organize content within each tab, and pages for individual topics:

```json
{
"navigation": {
"tabs": [
{
"tab": "User Guide",
"groups": [
{
"group": "Getting started",
"pages": ["quickstart", "installation"]
},
{
"group": "Advanced features",
"pages": ["customization", "integrations"]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "Authentication",
"pages": ["auth/overview", "auth/tokens"]
}
]
}
]
}
}
```

**Anchors with tabs** - Use anchors for persistent navigation to key resources while organizing main content in tabs:

```json
{
"navigation": {
"anchors": [
{
"anchor": "Support",
"icon": "life-buoy",
"href": "https://support.example.com"
}
],
"tabs": [
{
"tab": "Documentation",
"pages": ["overview", "guides"]
},
{
"tab": "API",
"pages": ["api/introduction"]
}
]
}
}
```

**Dropdowns with nested groups** - Use dropdowns for version or product selection with organized content underneath:

```json
{
"navigation": {
"dropdowns": [
{
"dropdown": "v2.0 Documentation",
"groups": [
{
"group": "Core concepts",
"pages": ["v2/concepts", "v2/architecture"]
},
{
"group": "API Reference",
"pages": ["v2/api/users", "v2/api/products"]
}
]
}
]
}
}
```

### Best practices for combining types

- **Use tabs** for major content divisions (user docs vs API docs vs tutorials)

Check warning on line 556 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L556

Use parentheses judiciously.
- **Use groups** to organize related pages within a section
- **Use anchors** for persistent access to external resources or key internal pages
- **Use dropdowns** for version selection or when you have multiple product lines
- **Limit nesting depth** to 3 levels maximum to avoid overwhelming users
- **Be consistent** with naming conventions and icon usage across navigation types

## Nesting

You can use any combination of anchors, tabs, and dropdowns. The components can be nested within each other interchangeably to create your desired navigation structure.

Check warning on line 565 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L565

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

<CodeGroup>

Expand Down Expand Up @@ -586,7 +684,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 687 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L687

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

Check warning on line 687 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L687

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

<CodeGroup>

Expand All @@ -610,10 +708,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 711 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L711

Avoid using 'will'.

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

Check warning on line 713 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L713

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 714 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L714

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

Check warning on line 714 in navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

navigation.mdx#L714

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

<CodeGroup>
Expand Down