Skip to content

Address feedback #2058

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 4 commits into from
Dec 5, 2025
Merged

Address feedback #2058

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7079a75
clarify nav nesting
ethanpalm Dec 5, 2025
026dede
specify AI SDK v4
ethanpalm Dec 5, 2025
3deff80
note nav limitations and add examples
ethanpalm Dec 5, 2025
11da8aa
update param descriptions
ethanpalm Dec 5, 2025
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
20 changes: 14 additions & 6 deletions api/assistant/create-assistant-message.mdx
View file
Open in desktop
Copy link
Contributor

@cdxker cdxker Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good, but could we also update the openapi spec here: openapi: POST /assistant/{domain}/message

with the extra parameters we added

Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,17 @@

## Integration with `useChat`

The recommended way to integrate the assistant API into your application is with the `useChat` hook from [Vercel's AI SDK](https://sdk.vercel.ai/docs).
The `useChat` hook from Vercel's AI SDK is the recommended way to integrate the assistant API into your application.

Check warning on line 8 in api/assistant/create-assistant-message.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/assistant/create-assistant-message.mdx#L8 

Use 'app' instead of 'application'.

<Note>
The Mintlify assistant API is compatible with **AI SDK v4**. If you use AI SDK v5 or later, you must configure a custom transport.
</Note>

<Steps>
<Step title="Install the AI SDK">
<Step title="Install AI SDK v4">

```bash
npm i ai
npm i ai@^4.1.15
```

</Step>
Expand All @@ -28,9 +32,7 @@
},
body: {
fp: 'anonymous',
messages: [
{ role: 'user', content: 'What is this documentation about?' }
]
retrievalPageSize: 5,
},
streamProtocol: 'data',
sendExtraMessageFields: true,
Expand All @@ -53,6 +55,12 @@
}
```

**Required configuration for Mintlify:**
- `streamProtocol: 'data'` - Required for streaming responses.
- `sendExtraMessageFields: true` - Required to send message metadata.
- `body.fp` - Fingerprint identifier (use 'anonymous' or a user identifier).

Check warning on line 61 in api/assistant/create-assistant-message.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/assistant/create-assistant-message.mdx#L61 

Use parentheses judiciously.
- `body.retrievalPageSize` - Number of search results to use (recommended: 5).

Check warning on line 62 in api/assistant/create-assistant-message.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/assistant/create-assistant-message.mdx#L62 

Use parentheses judiciously.

</Step>
</Steps>

Expand Down
4 changes: 2 additions & 2 deletions discovery-openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
"properties": {
"fp": {
"type": "string",
"description": "Browser fingerprint or arbitrary string identifier. There may be future functionality which allows you to get the messages for a given fingerprint"
"description": "Fingerprint identifier for tracking conversation sessions. Use 'anonymous' for anonymous users or provide a unique user identifier."
},
"threadId": {
"default": null,
Expand Down Expand Up @@ -381,7 +381,7 @@
"retrievalPageSize": {
"type": "number",
"default": 5,
"description": "Number of retrieval results to return"
"description": "Number of documentation search results to use for generating the response. Higher values provide more context but may increase response time. Recommended: 5."
},
"filter": {
"type": "object",
Expand Down
230 changes: 170 additions & 60 deletions organize/navigation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@

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

Choose one primary organizational pattern at the root level of your navigation. Once you've chosen your primary pattern, you can nest other navigation elements within it.

## Pages

Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository.
Expand Down Expand Up @@ -96,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 Down Expand Up @@ -173,6 +175,8 @@

In the `navigation` object, `menu` is an array where each entry is an object that requires an `item` field and can contain other navigation fields such as groups, pages, icons, or links to external pages.

Menu items can only contain groups, pages, and external links.

```json
{
"navigation": {
Expand Down Expand Up @@ -262,9 +266,13 @@
}
```

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L274 

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

```json
{
Expand All @@ -290,7 +298,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 301 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L301 

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

<img
className="block dark:hidden pointer-events-none"
Expand Down Expand Up @@ -405,10 +413,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 416 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L416 

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L419 

Use parentheses judiciously.

To control which endpoints appear, explicitly list the desired endpoints in a `pages` array.
</Note>
Expand Down Expand Up @@ -505,7 +513,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 516 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L516 

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 @@ -561,37 +569,37 @@

## Nesting

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L572 

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L574 

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

<CodeGroup>

```json Anchors
```json Tabs containing anchors
{
"navigation": {
"anchors": [
"tabs": [
{
"anchor": "Anchor 1",
"groups": [
"tab": "Documentation",
"anchors": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2",
"just-a-file"
]
"anchor": "Guides",
"icon": "book-open",
"pages": ["quickstart", "tutorial"]
},
{
"anchor": "API Reference",
"icon": "code",
"pages": ["api/overview", "api/endpoints"]
}
]
},
{
"anchor": "Anchor 2",
"tab": "Resources",
"groups": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
]
"group": "Help",
"pages": ["support", "faq"]
}
]
}
Expand All @@ -600,34 +608,130 @@
}
```

```json Anchors containing tabs
{
"navigation": {
"anchors": [
{
"anchor": "Documentation",
"icon": "book-open",
"tabs": [
{
"tab": "Guides",
"pages": ["quickstart", "tutorial"]
},
{
"tab": "API",
"pages": ["api/overview", "api/endpoints"]
}
]
},
{
"anchor": "Community",
"icon": "users",
"href": "https://community.example.com"
}
]
}
}
```

```json Tabs
```json Products containing tabs
{
"navigation": {
"tabs": [
"products": [
{
"tab": "Tab 1",
"groups": [
"product": "Platform",
"icon": "server",
"tabs": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2",
"just-a-file"
"tab": "Documentation",
"groups": [
{
"group": "Getting started",
"pages": ["platform/quickstart"]
}
]
},
{
"tab": "API Reference",
"pages": ["platform/api"]
}
]
},
{
"tab": "Tab 2",
"groups": [
"product": "Mobile SDK",
"icon": "mobile",
"pages": ["mobile/overview"]
}
]
}
}
```

```json Multi-product SaaS with tabs and menu
{
"navigation": {
"products": [
{
"product": "Platform",
"icon": "cloud",
"tabs": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
"tab": "Documentation",
"menu": [
{
"item": "Getting Started",
"icon": "rocket",
"groups": [
{
"group": "Setup",
"pages": ["platform/install", "platform/config"]
},
{
"group": "Core Concepts",
"pages": ["platform/concepts/auth", "platform/concepts/data"]
}
]
},
{
"item": "Guides",
"icon": "book",
"pages": ["platform/guides/deployment", "platform/guides/scaling"]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "REST API",
"pages": ["platform/api/users", "platform/api/projects"]
},
{
"group": "GraphQL",
"pages": ["platform/api/graphql/queries", "platform/api/graphql/mutations"]
}
]
}
]
},
{
"product": "Analytics",
"icon": "chart-bar",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["analytics/quickstart", "analytics/setup"]
}
]
},
{
"tab": "API",
"pages": ["analytics/api/events", "analytics/api/reports"]
}
]
}
Expand All @@ -636,41 +740,47 @@
}
```

```json Tabs with external anchor
```json Versioned docs with tabs
{
"navigation": {
"global": {
"anchors": [
{
"anchor": "Anchor 1",
"href": "https://mintlify.com/docs"
}
]
},
"tabs": [
"versions": [
{
"tab": "Tab 1",
"groups": [
"version": "v2.0",
"tabs": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2",
"just-a-file"
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["v2/quickstart", "v2/migration-from-v1"]
},
{
"group": "Features",
"pages": ["v2/features/auth", "v2/features/api"]
}
]
},
{
"tab": "API Reference",
"pages": ["v2/api/overview", "v2/api/endpoints"]
}
]
},
{
"tab": "Tab 2",
"groups": [
"version": "v1.0",
"tabs": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["v1/quickstart"]
}
]
},
{
"tab": "API Reference",
"pages": ["v1/api/overview"]
}
]
}
Expand All @@ -683,7 +793,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 796 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L796 

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

Check warning on line 796 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L796 

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

<CodeGroup>

Expand All @@ -707,10 +817,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 820 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L820 

Avoid using 'will'.

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

Check warning on line 822 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L822 

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L823 

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

Check warning on line 823 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L823 

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

<CodeGroup>
Expand Down