Skip to content
Mintlify
Mintlify

静态导出

通过 Mintlify REST API 生成自包含的文档静态导出,并以单个包的形式下载,用于自托管。

静态导出处于私有 Beta 阶段,需要企业协议。请联系 [email protected] 申请访问权限。

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

静态导出使用与包中的文件相对应的 .html URL。例如,/guides/getting-started 会变为 /guides/getting-started.html。此行为自动生效,无需任何配置。

canonical 和 sitemap 中的 URL 仍保持无扩展名。CloudFront 会自动解析这些 URL,但其他静态托管服务可能需要配置重写规则。

静态导出以异步作业的形式运行。你为某个项目启动作业,然后轮询其状态,直至可下载该包。

启动静态导出作业

使用你的项目 ID 调用 启动静态导出作业。API 会将作业加入队列并返回 jobId

每个部署同一时间只能有一个处于活动状态的作业。如果该部署已有作业处于 queuedrunning 状态,端点将返回 409。该端点的速率限制为每个组织每小时最多启动 10 个作业。

轮询作业并下载包

使用 jobId 轮询 获取静态导出作业状态,直到 statuscompleted。完成后的响应中会包含 bundleUrl(指向该包的有时限预签名 S3 链接)、sizeBytes 以及 expiresAt 时间戳。

请在 expiresAt 之前下载该包。过期后,可再次调用状态端点以获取新的 bundleUrl,底层的导出文件仍可复用,仅链接有时限。

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

功能CloudClient-hostedAir-gapped
文档搜索Configurable
AI 助手Configurable
网页分析Configurable
API playground(“Try it”)Configurable
静态导出包

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

从同一页面复制你的项目 ID,并将其用作 projectId 路径参数。

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

将包引用添加到 values 文件

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

values.yaml
staticExport:
  enabled: true
  # Presigned S3 link returned by the Get static export job status endpoint.
  bundleUrl: "https://mintlify-static-export-outputs-prod.s3.amazonaws.com/6520f3a1c9b1a20012ab34cd/export.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 自动化整个流程。

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

.github/workflows/static-export.yml
name: Publish static export

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

env:
  PROJECT_ID: proj_your_project_id

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/${{ env.PROJECT_ID }}/jobs \
            -H "Authorization: Bearer ${{ secrets.MINTLIFY_ADMIN_KEY }}" | jq -r '.jobId')
          echo "job_id=$JOB_ID" >> "$GITHUB_OUTPUT"

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

      - 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 仓库机密,并将 PROJECT_ID 设置为你项目的 ID。在部署之前,请配置集群凭据,例如使用 azure/setup-helm 和你的 Kubernetes 配置文件(kubeconfig)。

Was this page helpful?Suggest editsRaise issue