From 638bdb2b579c7dcee8c6637a9d07c2d4c3f99a31 Mon Sep 17 00:00:00 2001
From: brandonmcconnell <brandon@mintlify.com>
Date: Wed, 19 Aug 2026 20:22:24 -0700
Subject: [PATCH] docs: clarify which version shapes support sdk

A version with sdk only carries groups or pages. Versions that use tabs
declare sdk on a tab inside the version, with a unique directory per
version to avoid route collisions.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 api-playground/sdk-reference-setup.mdx | 49 +++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx
index 8f0ba35e6..46af463b6 100644
--- a/api-playground/sdk-reference-setup.mdx
+++ b/api-playground/sdk-reference-setup.mdx
@@ -86,7 +86,7 @@ A group with `sdk` can also list `pages` that you write yourself. Your pages app
 
   - A tab with `sdk` can include `groups`, but no other navigation structures, such as `pages`, `versions`, or `languages`. It also cannot include an `openapi`, `asyncapi`, or `graphql` property.
   - A group with `sdk` can include `pages` and nested groups, but cannot include a `graphql` property.
-  - A version with `sdk` generates pages scoped to that version. See [Version your SDK reference](#version-your-sdk-reference).
+  - A version with `sdk` can include `groups` or `pages`, but no other navigation structures. If a version uses `tabs`, declare `sdk` on a tab inside the version instead. See [Version your SDK reference](#version-your-sdk-reference).
 </Note>
 
 <ParamField path="format" type="string" required>
@@ -134,6 +134,53 @@ Declare `sdk` on a version node in `navigation.versions` to generate a separate
 
 When you omit `directory` on a version, generated pages default to `sdk-reference/<version>`, so versions do not collide. If you set `directory` explicitly, use a unique value for each version. Duplicate directories cause route collisions that fail the build.
 
+A version with `sdk` can include `groups` or `pages` alongside the generated reference. It cannot include other navigation structures, such as `tabs`, `languages`, `dropdowns`, `anchors`, `products`, or an `href`.
+
+### Versions that use tabs
+
+If a version organizes content with `tabs`, declare `sdk` on a tab inside the version instead of on the version itself. Set a unique `directory` for each version's tab so the generated routes do not collide.
+
+```json
+"navigation": {
+  "versions": [
+    {
+      "version": "v2",
+      "tabs": [
+        {
+          "tab": "Guides",
+          "pages": ["quickstart"]
+        },
+        {
+          "tab": "SDK reference",
+          "sdk": {
+            "format": "typedoc",
+            "source": "sdk-artifacts/typedoc-v2.json",
+            "directory": "v2/sdk-reference"
+          }
+        }
+      ]
+    },
+    {
+      "version": "v1",
+      "tabs": [
+        {
+          "tab": "Guides",
+          "pages": ["v1/quickstart"]
+        },
+        {
+          "tab": "SDK reference",
+          "sdk": {
+            "format": "typedoc",
+            "source": "sdk-artifacts/typedoc-v1.json",
+            "directory": "v1/sdk-reference"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
 ## Generated pages
 
 Mintlify adds the generated navigation groups after any `groups` on the tab. If you add `sdk` to a group, the generated groups appear after that group's `pages`. The groups vary by format and may represent modules, packages, namespaces, or symbol types.