From ee706780149b2660e95deb5008df99e18c900be7 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 6bd4ec7bc7..8f0ba35e6e 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 01ab7115245d81a611deb6a25c401d01646a91da 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 8f0ba35e6e..be01487b7a 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 701b2b17a8f5d94727416533c78b61b8804c6990 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 be01487b7a..9130585dd7 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 ebb239e912d7142ea31022d59c976e1b8071c356 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 9130585dd7..53e1a81151 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 56141d50a2512cb410fad7dbe4a43c15e804094b 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 53e1a81151..be01487b7a 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 e1bd782ac9dabb237638bd2247a75f654fb7b146 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 be01487b7a..53e1a81151 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 |