静态导出

使用静态导出 API 以编程方式将站点预渲染为一组自包含的静态文件，并将结果作为单个包下载。导出的包为纯 HTML、CSS 和 JavaScript，没有运行时依赖，因此你可以将其托管在任何静态文件存储或 CDN 上。

静态导出包中的页面 URL

静态导出包使用明确的 .html 页面 URL。/guides/getting-started 会变为 /guides/getting-started.html，首页则为 /index.html。这样 URL 与包中的文件相对应，可以直接部署到 S3 或普通静态托管，无需将无扩展名 URL 重写为文件路径。上传时请保留 .html 文件名。静态导出 API 会自动启用此格式，因此你无需修改文档配置。部署到 CloudFront 时，客户端导航和预取仍可正常工作。仅支持文件访问的托管服务则通过生成的 .html 链接支持整页导航。普通云托管生产站点不受影响。内置控件在进行内部导航时也会使用 .html 目标地址，包括版本和语言切换器、搜索结果、卡片、助手引用及 API playground 链接。查询字符串会保留，因此 API playground 链接仍可正常工作。

canonical 和 sitemap 中的 URL 仍保持无扩展名；自定义的客户端导航 URL 也可以继续使用无扩展名。CloudFront 部署会解析这些 URL，但仅提供文件的托管服务可能需要配置重写。

静态导出的工作原理

静态导出以异步作业的形式运行。你启动作业、轮询其状态，然后在作业完成后生成可下载的包。

启动静态导出作业

使用要导出的域名调用启动静态导出作业。API 将作业加入队列并返回 jobId。

查询作业状态

使用 jobId 轮询获取静态导出作业状态，直到 status 为 completed。在作业运行时，响应会包含实时的 progress 和 pageCount。

生成包

使用 jobId 调用生成导出包。API 会将导出打包为单个归档文件，并返回 bundleUrl（即静态导出包的预签名 S3 链接）以及 expiresAt 时间戳。请在 expiresAt 之前下载该包——过期后，可再次调用生成导出包获取新的链接。底层作业及其文件仍可复用；仅链接有时限。

按部署方式的功能支持

可用功能取决于你的部署托管方式。气隙（air-gapped）部署没有出站网络访问权限，因此任何依赖 Mintlify 云服务的功能均不可用。标记为 Configurable 的功能会根据你的环境配置有所不同。

功能	Client-hosted	Air-gapped
文档搜索	Configurable
AI 助手	Configurable
网页分析	Configurable
API playground（“Try it”）		Configurable
静态导出包

端点

启动静态导出作业：为部署启动一个静态导出作业。
获取静态导出作业状态：轮询正在运行作业的状态和进度。
生成导出包：打包已完成的作业，并返回该包的单个 S3 链接。

身份认证

使用你的 admin API 密钥对请求进行身份认证。你可以在控制台的 API keys 页面生成 admin API 密钥。Admin API 密钥以 mint_ 前缀开头，属于服务端机密——切勿在客户端代码中暴露。

将包部署到你的 Enterprise Helm chart

自托管的 Mintlify 通过 mintlify/enterprise 仓库中的 Helm chart 部署。当静态导出作业生成包后，将 chart 指向该包，部署环境便会从你自己的基础设施提供服务。

将包引用添加到 values 文件

将 values.yaml 中的静态导出字段设置为生成导出包返回的 bundleUrl。chart 会在启动时获取该包并将其作为当前版本提供服务。

values.yaml

staticExport:
  enabled: true
  # Presigned S3 link returned by the Generate export bundle endpoint.
  bundleUrl: "https://mintlify-static-exports.s3.amazonaws.com/se_3f9a2c1b8e7d4a06/bundle.tar.gz"
  # Optional: pin to a specific export version for reproducible rollouts.
  version: "2024-06-01"

发布 chart

使用 helm upgrade 应用更新后的 values。部署环境会下载该包，将其切换为当前站点，并从你的集群中提供服务。

helm upgrade --install mintlify mintlify/enterprise \
  --namespace mintlify \
  --create-namespace \
  -f values.yaml

由于预签名链接会过期，每当你发布新内容时，都需要重新生成包并再次执行升级，或使用 GitHub Actions 自动化整个流程。

使用 GitHub Action 自动化

以下模板工作流按计划或按需运行完整的导出流程。它会启动作业、轮询直至导出完成、生成包，并将新的 bundleUrl 应用到 Helm chart。

.github/workflows/static-export.yml

name: Publish static export

on:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * *" # Daily at 06:00 UTC

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - name: Start static export job
        id: start
        run: |
          JOB_ID=$(curl -s -X POST https://api.mintlify.com/v1/static-export/jobs \
            -H "Authorization: Bearer ${{ secrets.MINTLIFY_ADMIN_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"domain": "docs.example.com"}' | jq -r '.jobId')
          echo "job_id=$JOB_ID" >> "$GITHUB_OUTPUT"

      - name: Wait for the job to complete
        run: |
          for i in $(seq 1 60); do
            STATUS=$(curl -s https://api.mintlify.com/v1/static-export/jobs/${{ steps.start.outputs.job_id }} \
              -H "Authorization: Bearer ${{ secrets.MINTLIFY_ADMIN_KEY }}" | jq -r '.status')
            echo "status=$STATUS"
            [ "$STATUS" = "completed" ] && exit 0
            [ "$STATUS" = "failed" ] && exit 1
            sleep 10
          done
          echo "Timed out waiting for the export job to complete." >&2
          exit 1

      - name: Generate the bundle
        id: bundle
        run: |
          BUNDLE_URL=$(curl -s -X POST \
            https://api.mintlify.com/v1/static-export/jobs/${{ steps.start.outputs.job_id }}/bundle \
            -H "Authorization: Bearer ${{ secrets.MINTLIFY_ADMIN_KEY }}" | jq -r '.bundleUrl')
          echo "bundle_url=$BUNDLE_URL" >> "$GITHUB_OUTPUT"

      - name: Deploy to the Helm chart
        run: |
          helm upgrade --install mintlify mintlify/enterprise \
            --namespace mintlify \
            --set staticExport.enabled=true \
            --set staticExport.bundleUrl="${{ steps.bundle.outputs.bundle_url }}"

将你的 admin API 密钥保存为 MINTLIFY_ADMIN_KEY 仓库机密，并在部署步骤之前配置集群凭据（例如，使用 azure/setup-helm 和你的 kubeconfig）。

概览

AI

API 文档

最佳实践

Git

使用场景

静态导出包中的页面 URL

静态导出的工作原理

按部署方式的功能支持

端点

身份认证

将包部署到你的 Enterprise Helm chart

使用 GitHub Action 自动化

​静态导出包中的页面 URL

​静态导出的工作原理

​按部署方式的功能支持

​端点

​身份认证

​将包部署到你的 Enterprise Helm chart

​使用 GitHub Action 自动化

静态导出包中的页面 URL

静态导出的工作原理

按部署方式的功能支持

端点

身份认证

将包部署到你的 Enterprise Helm chart

使用 GitHub Action 自动化