From 7079a753f57554c90c0a1665335116343f2e8bcc Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 4 Dec 2025 17:17:14 -0800
Subject: [PATCH 1/4] clarify nav nesting
---
organize/navigation.mdx | 128 ++++++++++++++++++----------------------
1 file changed, 58 insertions(+), 70 deletions(-)
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index 722530afd..c87dbe086 100644
--- a/organize/navigation.mdx
+++ b/organize/navigation.mdx
@@ -8,6 +8,8 @@ The [navigation](/organize/settings#param-navigation) property in `docs.json` co
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.
@@ -262,9 +264,13 @@ In the `navigation` object, `anchors` is an array where each entry is an object
}
```
-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
+
+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.
-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.
+
+ Global anchors must include an `href` field pointing to an external URL. They cannot contain relative paths.
+
```json
{
@@ -561,37 +567,37 @@ For automated translations, [contact our sales team](mailto:gtm@mintlify.com) to
## 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 navigation pattern such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern.
+
+### Nesting examples
-```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"]
}
]
}
@@ -600,79 +606,61 @@ You can use any combination of anchors, tabs, dropdowns, and products. The compo
}
```
-
-```json Tabs
+```json Anchors containing tabs
{
"navigation": {
- "tabs": [
+ "anchors": [
{
- "tab": "Tab 1",
- "groups": [
+ "anchor": "Documentation",
+ "icon": "book-open",
+ "tabs": [
{
- "group": "Group 1",
- "pages": [
- "some-folder/file-1",
- "another-folder/file-2",
- "just-a-file"
- ]
+ "tab": "Guides",
+ "pages": ["quickstart", "tutorial"]
+ },
+ {
+ "tab": "API",
+ "pages": ["api/overview", "api/endpoints"]
}
]
},
{
- "tab": "Tab 2",
- "groups": [
- {
- "group": "Group 2",
- "pages": [
- "some-other-folder/file-1",
- "various-different-folders/file-2",
- "another-file"
- ]
- }
- ]
+ "anchor": "Community",
+ "icon": "users",
+ "href": "https://community.example.com"
}
]
}
}
```
-```json Tabs with external anchor
+```json Products containing tabs
{
"navigation": {
- "global": {
- "anchors": [
- {
- "anchor": "Anchor 1",
- "href": "https://mintlify.com/docs"
- }
- ]
- },
- "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": [
- {
- "group": "Group 2",
- "pages": [
- "some-other-folder/file-1",
- "various-different-folders/file-2",
- "another-file"
- ]
- }
- ]
+ "product": "Mobile SDK",
+ "icon": "mobile",
+ "pages": ["mobile/overview"]
}
]
}
From 026dedef2c0295ee0991655fcfbaee62e99aac1d Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 4 Dec 2025 17:29:51 -0800
Subject: [PATCH 2/4] specify AI SDK v4
---
api/assistant/create-assistant-message.mdx | 20 ++++++++++++++------
1 file changed, 14 insertions(+), 6 deletions(-)
diff --git a/api/assistant/create-assistant-message.mdx b/api/assistant/create-assistant-message.mdx
index 8c878c86e..7cc8bf120 100644
--- a/api/assistant/create-assistant-message.mdx
+++ b/api/assistant/create-assistant-message.mdx
@@ -5,13 +5,17 @@ keywords: ["assistant message", "embed", "chat", "integrate"]
## 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.
+
+
+ The Mintlify assistant API is compatible with **AI SDK v4**. If you use AI SDK v5 or later, you must configure a custom transport.
+
-
+
```bash
-npm i ai
+npm i ai@^4.1.15
```
@@ -28,9 +32,7 @@ function MyComponent({ domain }) {
},
body: {
fp: 'anonymous',
- messages: [
- { role: 'user', content: 'What is this documentation about?' }
- ]
+ retrievalPageSize: 5,
},
streamProtocol: 'data',
sendExtraMessageFields: true,
@@ -53,6 +55,12 @@ function MyComponent({ domain }) {
}
```
+**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).
+- `body.retrievalPageSize` - Number of search results to use (recommended: 5).
+
From 3deff8030e700db3e454ee95f89d94d0d8d20c4e Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 4 Dec 2025 17:43:10 -0800
Subject: [PATCH 3/4] note nav limitations and add examples
---
organize/navigation.mdx | 126 +++++++++++++++++++++++++++++++++++++++-
1 file changed, 124 insertions(+), 2 deletions(-)
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index c87dbe086..cad650fa2 100644
--- a/organize/navigation.mdx
+++ b/organize/navigation.mdx
@@ -175,6 +175,8 @@ Menus add dropdown navigation items to a tab. Use menus to help users go directl
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": {
@@ -567,9 +569,9 @@ For automated translations, [contact our sales team](mailto:gtm@mintlify.com) to
## Nesting
-Navigation elements can be nested within each other to create complex hierarchies. You must have one root-level navigation pattern such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern.
+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.
-### Nesting examples
+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.
@@ -667,6 +669,126 @@ Navigation elements can be nested within each other to create complex hierarchie
}
```
+```json Multi-product SaaS with tabs and menu
+{
+ "navigation": {
+ "products": [
+ {
+ "product": "Platform",
+ "icon": "cloud",
+ "tabs": [
+ {
+ "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"]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+```json Versioned docs with tabs
+{
+ "navigation": {
+ "versions": [
+ {
+ "version": "v2.0",
+ "tabs": [
+ {
+ "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"]
+ }
+ ]
+ },
+ {
+ "version": "v1.0",
+ "tabs": [
+ {
+ "tab": "Documentation",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": ["v1/quickstart"]
+ }
+ ]
+ },
+ {
+ "tab": "API Reference",
+ "pages": ["v1/api/overview"]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
## Breadcrumbs
From 11da8aa459167c9c87abc47cc58d76bef1df08ea Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 4 Dec 2025 19:19:43 -0800
Subject: [PATCH 4/4] update param descriptions
---
discovery-openapi.json | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/discovery-openapi.json b/discovery-openapi.json
index 067e51387..ea525b1b5 100644
--- a/discovery-openapi.json
+++ b/discovery-openapi.json
@@ -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,
@@ -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",