Document monorepo and multi-repo SDK reference setups

api-playground/sdk-reference-setup.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Generate SDK reference pages from doc-tool output"
 sidebarTitle: "SDK reference setup"
 description: "Publish SDK reference documentation in Mintlify from TypeDoc, DocFX, Javadoc, Sphinx, or phpDocumentor artifacts using the sdk navigation property."
 keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"]
 ---
 
@@ -115,3 +115,31 @@
 ## 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.
+
+## Repository setup
+
+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
+
+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.
+
+```txt
+docs-repo/
+  docs.json
+  content/
+  sdk-artifacts/
+    typedoc.json
+```
+
+### SDK in a separate repository
+
+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 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. 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.
+
+<Tip>
+  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.
+</Tip>