From 89e3bd816d5124ab2e6fad67a0dc92c98ee4f8d0 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 1 Aug 2026 19:41:23 +0000 Subject: [PATCH 1/6] docs: document monorepo and multi-repo SDK reference setups --- api-playground/sdk-reference-setup.mdx | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index c414fb6e5..806399b23 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -115,3 +115,25 @@ Remote artifacts have a 50 MB download limit and a 200 MB extracted size limit. ## Keep references up to date Regenerate the artifact whenever your SDK changes. A common pattern is a CI job in each SDK repository that runs the documentation tool on release. The job either commits the artifact to your docs repository or uploads it to a stable URL that `source` points to. + +## Where your SDK code lives + +Your SDK code does not need to live in the same repository as your docs. Pick the pattern that matches your setup. + +### SDK and docs in the same repository + +The simplest setup. Generate the artifact in the same repository as your docs and point `source` at its relative path. Any workflow that already produces the artifact on push or release can commit it back to the repository, and the next docs deployment picks it up automatically. + +This works for a monorepo that contains both the SDK source and the docs, or for a docs repository that vendors the SDK as a submodule. + +### SDK in a separate repository + +When the SDK lives in its own repository, you have two options. + +**Commit the artifact to your docs repository.** In the SDK repository, run a CI job on release that generates the artifact and opens a pull request (or pushes a commit) to your docs repository with the updated file. Merging that change to your deployment branch triggers a docs deployment on its own, so no extra API call is needed. Point `source` at the committed path, the same as the single-repository setup. + +**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) and set `source` to that URL. Because nothing changes in your docs repository when the SDK updates, you also need to trigger a docs deployment so the new artifact is fetched. Call the [Trigger deployment](/api/update/trigger) endpoint from your SDK release pipeline after the artifact is published. See [Remote artifact limits](#use-remote-sources) for size constraints. + + + Prefer committing the artifact when your SDK release cadence is low or you want the docs repository to be the source of truth. Prefer hosting the artifact when releases are frequent, artifacts are large, or you already publish them (for example, Javadoc jars on Maven Central). + From 7e1fe9da3fdf2630af9f3b9b90e64ab45e55b429 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 1 Aug 2026 19:45:00 +0000 Subject: [PATCH 2/6] docs: rename section to "Where do the docs and code live?" --- 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 806399b23..6094c27c5 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -116,7 +116,7 @@ Remote artifacts have a 50 MB download limit and a 200 MB extracted size limit. Regenerate the artifact whenever your SDK changes. A common pattern is a CI job in each SDK repository that runs the documentation tool on release. The job either commits the artifact to your docs repository or uploads it to a stable URL that `source` points to. -## Where your SDK code lives +## Where do the docs and code live? Your SDK code does not need to live in the same repository as your docs. Pick the pattern that matches your setup. From e85ffb00e5c40e1ad4a9e265e232952d874ebd6e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 1 Aug 2026 19:45:40 +0000 Subject: [PATCH 3/6] docs: drop submodule mention from SDK-and-docs same-repo pattern --- 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 6094c27c5..9e9ba7913 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -124,7 +124,7 @@ Your SDK code does not need to live in the same repository as your docs. Pick th The simplest setup. Generate the artifact in the same repository as your docs and point `source` at its relative path. Any workflow that already produces the artifact on push or release can commit it back to the repository, and the next docs deployment picks it up automatically. -This works for a monorepo that contains both the SDK source and the docs, or for a docs repository that vendors the SDK as a submodule. +This works for a monorepo that contains both the SDK source and the docs. ### SDK in a separate repository From 04b4a596d52ac26061f70a26ac5b366b7d693076 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 1 Aug 2026 19:58:22 +0000 Subject: [PATCH 4/6] docs: number the separate-repo SDK options --- api-playground/sdk-reference-setup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index 9e9ba7913..5a044b6be 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -130,9 +130,9 @@ This works for a monorepo that contains both the SDK source and the docs. When the SDK lives in its own repository, you have two options. -**Commit the artifact to your docs repository.** In the SDK repository, run a CI job on release that generates the artifact and opens a pull request (or pushes a commit) to your docs repository with the updated file. Merging that change to your deployment branch triggers a docs deployment on its own, so no extra API call is needed. Point `source` at the committed path, the same as the single-repository setup. +1. **Commit the artifact to your docs repository.** In the SDK repository, run a CI job on release that generates the artifact and opens a pull request (or pushes a commit) to your docs repository with the updated file. Merging that change to your deployment branch triggers a docs deployment on its own, so no extra API call is needed. Point `source` at the committed path, the same as the single-repository setup. -**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) and set `source` to that URL. Because nothing changes in your docs repository when the SDK updates, you also need to trigger a docs deployment so the new artifact is fetched. Call the [Trigger deployment](/api/update/trigger) endpoint from your SDK release pipeline after the artifact is published. See [Remote artifact limits](#use-remote-sources) for size constraints. +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) and set `source` to that URL. Because nothing changes in your docs repository when the SDK updates, you also need to trigger a docs deployment so the new artifact is fetched. Call the [Trigger deployment](/api/update/trigger) endpoint from your SDK release pipeline after the artifact is published. See [Remote artifact limits](#use-remote-sources) for size constraints. Prefer committing the artifact when your SDK release cadence is low or you want the docs repository to be the source of truth. Prefer hosting the artifact when releases are frequent, artifacts are large, or you already publish them (for example, Javadoc jars on Maven Central). From 7842ac3a31b445baae5498e51f9450467b04d5b6 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:19:29 -0700 Subject: [PATCH 5/6] copy edit --- api-playground/sdk-reference-setup.mdx | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index 5a044b6be..838a9fe6b 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -116,24 +116,30 @@ Remote artifacts have a 50 MB download limit and a 200 MB extracted size limit. Regenerate the artifact whenever your SDK changes. A common pattern is a CI job in each SDK repository that runs the documentation tool on release. The job either commits the artifact to your docs repository or uploads it to a stable URL that `source` points to. -## Where do the docs and code live? +## Repository setup -Your SDK code does not need to live in the same repository as your docs. Pick the pattern that matches your setup. +Store your SDK code and documentation in the same repository or separate repositories. Pick the pattern that matches your setup. Both options have full functionality. -### SDK and docs in the same repository +### SDK and documentation in the same repository -The simplest setup. Generate the artifact in the same repository as your docs and point `source` at its relative path. Any workflow that already produces the artifact on push or release can commit it back to the repository, and the next docs deployment picks it up automatically. +Generate your SDK artifact in the same repository as your documentation and point `source` at its relative path. Any workflow that already produces the artifact on push or release can commit it back to the repository, and publish updates as part of the next documentation site deployment. -This works for a monorepo that contains both the SDK source and the docs. +```txt +docs-repo/ + docs.json + content/ + sdk-artifacts/ + typedoc.json +``` ### SDK in a separate repository -When the SDK lives in its own repository, you have two options. +When the SDK is in its own repository, you have two options. -1. **Commit the artifact to your docs repository.** In the SDK repository, run a CI job on release that generates the artifact and opens a pull request (or pushes a commit) to your docs repository with the updated file. Merging that change to your deployment branch triggers a docs deployment on its own, so no extra API call is needed. Point `source` at the committed path, the same as the single-repository setup. +1. **Commit the artifact to your documentation repository.** In the SDK repository, run a CI job on release that generates the artifact and opens a pull request (or pushes a commit) to your documentation repository with the updated file. Merge that change to your deployment branch to trigger a site deployment. Point `source` at the committed path, the same as 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) and set `source` to that URL. Because nothing changes in your docs repository when the SDK updates, you also need to trigger a docs deployment so the new artifact is fetched. Call the [Trigger deployment](/api/update/trigger) endpoint from your SDK release pipeline after the artifact is published. See [Remote artifact limits](#use-remote-sources) for size constraints. +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. - Prefer committing the artifact when your SDK release cadence is low or you want the docs repository to be the source of truth. Prefer hosting the artifact when releases are frequent, artifacts are large, or you already publish them (for example, Javadoc jars on Maven Central). + 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. From 6345c0264c80786414c36d4faaf82845de20e060 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:25:29 -0700 Subject: [PATCH 6/6] Vale --- 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 838a9fe6b..dac43f650 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -118,7 +118,7 @@ Regenerate the artifact whenever your SDK changes. A common pattern is a CI job ## Repository setup -Store your SDK code and documentation in the same repository or separate repositories. Pick the pattern that matches your setup. Both options have full functionality. +Store your SDK code and documentation in the same repository or separate repositories. Pick the pattern that matches your setup. Both options support the same capabilities. ### SDK and documentation in the same repository