Skip to content
Draft
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
44 changes: 30 additions & 14 deletions organize/navigation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,11 @@

With proper navigation configuration, you can organize your content so that users can find exactly what they're looking for.

## Pages
## Basic navigation components

These are the fundamental building blocks for organizing your documentation.

### Pages

Pages are the most fundamental navigation component. Pages map to the MDX files that make up your documentation.

Expand Down Expand Up @@ -39,7 +43,7 @@
}
```

## Groups
### Groups

Use groups to organize your sidebar navigation into sections. Groups can be nested within each other, labeled with tags, and styled with icons.

Expand Down Expand Up @@ -103,7 +107,11 @@
}
```

## Tabs
## Top-level navigation structures

These components create major divisions in your documentation and appear at the top level of your navigation hierarchy.

### 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 @@ -153,7 +161,7 @@
}
```

### Menus
#### Menus within tabs

Menus add dropdown navigation items to a tab. Use menus to help users go directly to specific pages within a tab.

Expand Down Expand Up @@ -199,7 +207,7 @@
}
```

## Anchors
### Anchors

Anchors add persistent navigation items to the top of your sidebar. Use anchors to section your content, provide quick access to external resources, or create prominent calls to action.

Expand Down Expand Up @@ -248,9 +256,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 259 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L259

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 261 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L261

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

```json
{
Expand All @@ -274,9 +282,9 @@
}
```

## Dropdowns
### 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 287 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L287

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

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

## Products
### Products

<img
className="block dark:hidden pointer-events-none"
Expand Down Expand Up @@ -387,11 +395,15 @@
}
```

## OpenAPI
## Advanced features

These features provide specialized functionality for complex documentation needs.

Check warning on line 400 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L400

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

### OpenAPI integration

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 406 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L406

Avoid using 'will'.

```json
{
Expand Down Expand Up @@ -422,7 +434,7 @@

For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).

## Versions
### Versions

Partition your navigation into different versions. Versions are selectable from a dropdown menu.

Expand Down Expand Up @@ -467,7 +479,7 @@
}
```

## Languages
### Languages

Partition your navigation into different languages. Languages are selectable from a dropdown menu.

Expand All @@ -485,7 +497,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 500 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L500

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 @@ -533,9 +545,13 @@

For automated translations, [contact our sales team](mailto:gtm@mintlify.com) to discuss solutions.

## Nesting
## Navigation patterns

Learn how to combine navigation components and configure their behavior.

### Nesting components

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

Check warning on line 554 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L554

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

<CodeGroup>

Expand Down Expand Up @@ -655,9 +671,9 @@

</CodeGroup>

## Breadcrumbs
### 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 676 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L676

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

Check warning on line 676 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L676

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

<CodeGroup>

Expand All @@ -675,16 +691,16 @@

</CodeGroup>

## Interaction configuration
### Interaction configuration

Control how users interact with navigation elements using the `interaction` property in your `docs.json`.

### Enable auto-navigation for groups
#### 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 700 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L700

Avoid using 'will'.

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

Check warning on line 702 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L702

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 703 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L703

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

Check warning on line 703 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L703

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

<CodeGroup>
Expand Down