Exportación estática

Usa la API de exportación estática para prerenderizar tu sitio de forma programática en un conjunto autocontenido de archivos estáticos y descargar el resultado como un único paquete. El paquete exportado es HTML, CSS y JavaScript puros, sin dependencias en tiempo de ejecución, por lo que puedes alojarlo en cualquier almacenamiento de archivos estáticos o CDN.

Las exportaciones estáticas usan URLs .html que coinciden con los archivos del paquete. Por ejemplo, /guides/getting-started se convierte en /guides/getting-started.html. Esto sucede de forma automática y no requiere configuración.

Una exportación estática se ejecuta como un trabajo asíncrono. Inicias el trabajo para un proyecto y luego consultas su estado hasta que el paquete esté listo para descargar.

Las funciones disponibles dependen de cómo alojes tu despliegue. Los despliegues aislados (air-gapped) no tienen acceso saliente a la red, por lo que cualquier función que dependa de los servicios en la nube de Mintlify no está disponible. Las funciones etiquetadas como Configurable tienen distinta disponibilidad según la configuración de tu entorno.

• Iniciar trabajo de exportación estática: Pone en cola un trabajo de exportación estática para un proyecto.
• Obtener estado del trabajo de exportación estática: Consulta el estado del trabajo y, una vez completado, recupera un enlace prefirmado para descargar el paquete.

Autentica las solicitudes con tu clave de API de administrador. Genera una clave de API de administrador en la página de claves de API de tu panel. Las claves de API de administrador comienzan con el prefijo mint_ y son secretos del lado del servidor: no las expongas en código del lado del cliente.

Copia tu ID de proyecto desde la misma página y úsalo como el parámetro de ruta projectId.

Mintlify autoalojado se implementa con el Helm chart del repositorio mintlify/enterprise. Una vez que un trabajo de exportación estática se completa, apuntas el chart al bundleUrl y el despliegue lo sirve desde tu propia infraestructura.

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"

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

Dado que los enlaces prefirmados expiran, vuelve a consultar el estado del trabajo y a ejecutar la actualización siempre que publiques contenido nuevo, o automatiza el ciclo con GitHub Actions.

La siguiente plantilla de workflow ejecuta todo el ciclo de exportación de forma programada o bajo demanda. Inicia un trabajo, espera hasta que la exportación se complete y despliega el nuevo bundleUrl en el Helm chart.

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 }}"

Guarda tu clave de API de administrador como el secret de repositorio MINTLIFY_ADMIN_KEY y establece PROJECT_ID con el ID de tu proyecto. Antes de desplegar, configura las credenciales del clúster, por ejemplo con azure/setup-helm y tu archivo de configuración de Kubernetes (kubeconfig).