From b980953ba4be2291c75abef4f8e8f324545e1b38 Mon Sep 17 00:00:00 2001 From: brandonmcconnell Date: Wed, 19 Aug 2026 16:54:13 -0700 Subject: [PATCH 1/6] docs: document sdk on version nodes Co-authored-by: Cursor --- api-playground/sdk-reference-setup.mdx | 32 ++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index 6bd4ec7bc..8f0ba35e6 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -82,10 +82,11 @@ Add `sdk` to a [group](/organize/navigation#groups) to generate pages inside one A group with `sdk` can also list `pages` that you write yourself. Your pages appear first, followed by the generated reference groups. - You can declare `sdk` on a [tab](/organize/navigation#tabs) or a [group](/organize/navigation#groups). + You can declare `sdk` on a [tab](/organize/navigation#tabs), a [group](/organize/navigation#groups), or a [version](/organize/navigation#versions). - 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). @@ -97,7 +98,7 @@ A group with `sdk` can also list `pages` that you write yourself. Your pages app - The URL path prefix for generated pages. Defaults to `sdk-reference`. + The URL path prefix for generated pages. Defaults to `sdk-reference`, or `sdk-reference/` when declared on a version. Add multiple tabs or groups to document multiple libraries. For example, use two groups in the same tab for the stable and beta versions of an SDK. Use a unique `directory` for each library to avoid route collisions. @@ -106,6 +107,33 @@ Add multiple tabs or groups to document multiple libraries. For example, use two Add your artifact directory to [`.mintignore`](/organize/mintignore) so Mintlify treats artifacts as build inputs rather than publishing them as static assets. +## Version your SDK reference + +Declare `sdk` on a version node in `navigation.versions` to generate a separate reference for each version of your SDK. Point each version's `source` at the artifact for that release. + +```json +"navigation": { + "versions": [ + { + "version": "v2", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/typedoc-v2.json" + } + }, + { + "version": "v1", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/typedoc-v1.json" + } + } + ] +} +``` + +When you omit `directory` on a version, generated pages default to `sdk-reference/`, 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. + ## 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. From 91ae6ff4bebe20c8740ddc1fbaddee1fb373449c Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Mon, 24 Aug 2026 05:10:46 +0000 Subject: [PATCH 2/6] Updated mintlify pages - Updated api-playground/sdk-reference-setup.mdx Mintlify-Source: dashboard-editor --- api-playground/sdk-reference-setup.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index 8f0ba35e6..be01487b7 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -7,6 +7,8 @@ keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "ref Use the `sdk` navigation property to generate reference pages for your SDK libraries from the documentation tools you already run. Mintlify reads each tool's build artifact. It creates a page for every class, interface, module, and function. It also includes navigation groups, cross-page links, and search indexing. +/ + ## Supported formats | `format` | Tool | Artifact | @@ -227,9 +229,8 @@ docs-repo/ When the SDK is in its own repository, you have two options. 1. **Commit the artifact to your documentation repository.** In the SDK repository, run a CI job at release time. The job generates the artifact and opens a pull request or pushes a commit with the updated file to your documentation repository. Merge the change into your deployment branch to trigger a site deployment. Point `source` at the committed path, as in the single-repository setup. - 2. **Host the artifact and fetch it at build time.** Upload the artifact to a stable HTTPS URL. For example, an S3 bucket, GitHub Releases asset, or Maven Central for Javadoc jars. Set `source` to the URL. Trigger a documentation site deployment to fetch the new artifact whenever you update it. Call the [Trigger deployment](/api/update/trigger) endpoint from your SDK release pipeline after you publish the artifact. If your release cadence is low or you want the documentation repository to be the source of truth, commit the artifact to your documentation repository. If your releases are frequent, artifacts are large, or you already publish them (for example, Javadoc jars on Maven Central), host the artifact and fetch it at build time. - + \ No newline at end of file From 8b164a86c3e9bec848c1d3e2d5498272a4b83af2 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Mon, 24 Aug 2026 05:12:13 +0000 Subject: [PATCH 3/6] Updated mintlify pages - Updated api-playground/sdk-reference-setup.mdx Mintlify-Source: dashboard-editor --- api-playground/sdk-reference-setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index be01487b7..9130585dd 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -7,7 +7,7 @@ keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "ref Use the `sdk` navigation property to generate reference pages for your SDK libraries from the documentation tools you already run. Mintlify reads each tool's build artifact. It creates a page for every class, interface, module, and function. It also includes navigation groups, cross-page links, and search indexing. -/ +## / ## Supported formats From 1fec96669946d3a621f0388fbd3fbeccb3540edc Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Mon, 24 Aug 2026 05:12:49 +0000 Subject: [PATCH 4/6] Updated mintlify pages - Updated api-playground/sdk-reference-setup.mdx Mintlify-Source: dashboard-editor --- api-playground/sdk-reference-setup.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index 9130585dd..53e1a8115 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -7,8 +7,6 @@ keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "ref Use the `sdk` navigation property to generate reference pages for your SDK libraries from the documentation tools you already run. Mintlify reads each tool's build artifact. It creates a page for every class, interface, module, and function. It also includes navigation groups, cross-page links, and search indexing. -## / - ## Supported formats | `format` | Tool | Artifact | From 405ea4725461f573acc9cdc3ecf59c1d5995b786 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Mon, 24 Aug 2026 05:13:13 +0000 Subject: [PATCH 5/6] Updated mintlify pages - Updated api-playground/sdk-reference-setup.mdx Mintlify-Source: dashboard-editor --- api-playground/sdk-reference-setup.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index 53e1a8115..be01487b7 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -7,6 +7,8 @@ keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "ref Use the `sdk` navigation property to generate reference pages for your SDK libraries from the documentation tools you already run. Mintlify reads each tool's build artifact. It creates a page for every class, interface, module, and function. It also includes navigation groups, cross-page links, and search indexing. +/ + ## Supported formats | `format` | Tool | Artifact | From 024dcf2243a75eaa6f504e5a1da0cf192264d365 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Mon, 24 Aug 2026 05:14:01 +0000 Subject: [PATCH 6/6] Updated mintlify pages - Updated api-playground/sdk-reference-setup.mdx Mintlify-Source: dashboard-editor --- api-playground/sdk-reference-setup.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index be01487b7..53e1a8115 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -7,8 +7,6 @@ keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "ref Use the `sdk` navigation property to generate reference pages for your SDK libraries from the documentation tools you already run. Mintlify reads each tool's build artifact. It creates a page for every class, interface, module, and function. It also includes navigation groups, cross-page links, and search indexing. -/ - ## Supported formats | `format` | Tool | Artifact |