SDK 参考设置

使用 sdk 导航属性，可以基于你已经在使用的文档工具，为 SDK 库生成参考页面。Mintlify 会读取每个工具生成的构建产物，为每个 class、interface、module 和 function 创建一个页面，并自动生成导航分组、跨页链接与搜索索引。

以机器可读的输出格式运行你的文档工具。如果你已经在 CI 中发布生成的文档，通常只需在同一命令中添加一个参数即可。

npx typedoc --json typedoc.json src/index.ts

在 docs.json 的某个 tab 或 group 中添加 sdk 属性。Mintlify 会解析该构建产物，并为该库创建导航分组和页面。

"navigation": {
  "tabs": [
    {
      "tab": "SDK Reference",
      "sdk": {
        "format": "typedoc",
        "source": "sdk-artifacts/typedoc.json",
        "directory": "sdk/typescript"
      }
    }
  ]
}

在 group 上添加 sdk，即可只在 tab 的某一部分生成页面，而不是占用整个 tab。Group 和页面会继承其父级 tab 或 group 的 sdk 设置。如果嵌套的 group 定义了自己的 sdk，Mintlify 会使用该设置，而不是继承的设置。

{
  "group": "TypeScript SDK",
  "sdk": {
    "format": "typedoc",
    "source": "sdk-artifacts/typedoc.json",
    "directory": "sdk/typescript"
  },
  "pages": ["sdk/typescript/overview"]
}

包含 sdk 的 group 也可以列出你自己编写的 pages。你的页面会显示在前面，生成的参考分组紧随其后。

添加多个 tab 或 group 即可为多个库生成文档。例如，在同一个 tab 中使用两个 group，分别对应某个 SDK 的稳定版和 beta 版。为每个库使用唯一的 directory，以避免路由冲突。

Mintlify 会将生成的导航组添加到 tab 中已有的任何 groups 之后。如果你在 group 上添加了 sdk，生成的分组会显示在该 group 的 pages 之后。这些组因格式而异，可能表示模块、包、命名空间或符号类型。

每个生成的页面都记录了构建产物中的一个类、接口、函数、类型或其他符号，并链接到相关的生成页面。如果转换器生成的页面不属于任何组，Mintlify 会将它们归入 Reference 组。

在 MDX 页面上使用 sdk frontmatter，可将构建产物中的某个符号作为目标。Mintlify 会先渲染你编写的任何正文内容，然后在其下方追加该符号对应的生成参考内容。当你希望在某个特定的 class、interface 或 method 之上添加示例、迁移说明或上下文时，可以使用这种方式。

像其他页面一样，将该页面添加到 docs.json 的导航中。Mintlify 只会为出现在导航中的页面生成 SDK 内容。

当包含 sdk 的 tab 或 group 中存在带有 sdk frontmatter 的页面时，Mintlify 会停止自动填充该 tab 或 group，只显示你编写的页面。如果你希望该库的其余部分继续自动填充，请将该页面移到该 tab 或 group 之外。

让 sdk 指向某个符号：

---
title: "Client"
sdk: "class Client"
---

创建一个 `Client` 来调用 API。

字符串形式遵循 [source] kind name 的模式。如果省略 source，页面会从 tab 或 group 的 sdk 配置继承。字符串形式始终继承 format，因此只能用于带有 sdk 的 tab 或 group 下的页面。其他情况下，请将 sdk 设置为包含下述字段的对象。对于 method 和 property，请包含父级名称，例如 method Client.getUser。

如果省略 title 或 description，Mintlify 会使用为该符号生成的标题和描述。

将 source 设置为 HTTPS URL，即可在构建时获取构建产物，而无需将其提交到文档仓库中。

单文件格式（typedoc、phpdoc）可直接接受文件 URL。目录格式（docfx、javadoc、sphinx）接受 zip 压缩包。发布到 Maven Central 的 Javadoc jar 无需重新打包即可使用：

{
  "tab": "Java SDK",
  "sdk": {
    "format": "javadoc",
    "source": "https://repo1.maven.org/maven2/com/example/my-library/1.0.0/my-library-1.0.0-javadoc.jar",
    "directory": "sdk/java"
  }
}

远程构建产物的下载大小上限为 50 MB，解压后大小上限为 200 MB。

在你的 SDK 发生变化后，重新生成构建产物。常见做法是在每个 SDK 仓库中设置 CI 任务，在发布时运行文档工具。该任务可以将构建产物提交到文档仓库，或上传到 source 所指向的稳定 URL。

在同一仓库或不同仓库中存储 SDK 代码和文档。选择符合你工作方式的模式。这两种方式支持相同的功能。

在与文档相同的仓库中生成 SDK 构建产物，并将 source 指向其相对路径。任何在 push 或 release 时生成构建产物的工作流都可以将其提交回仓库，并在下一次文档站点部署时发布更新。

docs-repo/
  docs.json
  content/
  sdk-artifacts/
    typedoc.json

当 SDK 位于自己的仓库中时，有两种方式。

1. 将构建产物提交到文档仓库。 在 SDK 仓库中设置一个在发布时运行的 CI 任务。该任务生成构建产物，并向文档仓库发起拉取请求（或推送提交），其中包含更新后的文件。将此更改合并到部署分支以触发站点部署。将 source 指向已提交的路径，与单仓库设置相同。

2. 托管构建产物并在构建时获取。 将构建产物上传到稳定的 HTTPS URL，例如 S3 存储桶、GitHub Releases 资源或 Maven Central 上的 Javadoc jar。将 source 设置为该 URL。每次更新构建产物时，触发文档站点部署以获取新构建产物。发布构建产物后，从 SDK 发布流水线调用触发部署端点。