Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions api/static-export/generate-bundle.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: "Generate export bundle"
openapi: "/static-export-openapi.json POST /static-export/jobs/{jobId}/bundle"

Check warning on line 3 in api/static-export/generate-bundle.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/static-export/generate-bundle.mdx#L3

Use 'JSON' instead of 'json'.
keywords: ["static export", "bundle", "s3", "download", "enterprise"]
---

<Info>
Static export requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-export).
</Info>

10 changes: 10 additions & 0 deletions api/static-export/get-job-status.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: "Get static export job status"
openapi: "/static-export-openapi.json GET /static-export/jobs/{jobId}"

Check warning on line 3 in api/static-export/get-job-status.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/static-export/get-job-status.mdx#L3

Use 'JSON' instead of 'json'.
keywords: ["static export", "job", "status", "progress", "enterprise"]
---

<Info>
Static export requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-export).
</Info>

136 changes: 136 additions & 0 deletions api/static-export/overview.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
---
title: "Static export"
description: "Generate a self-contained static export of your documentation and download it as a single bundle through the Mintlify REST API."
keywords: ["static export", "static site", "bundle", "self-host", "enterprise"]
---

<Info>
Static export requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-export).
</Info>

Use the static export API to programmatically pre-render your site into a self-contained set of static files and download the result as a single bundle. The exported bundle is pure HTML, CSS, and JavaScript with no runtime dependencies, so you can host it on any static file storage or CDN.

## How static export works

A static export runs as an asynchronous job. You start the job, poll for its status, and then generate a downloadable bundle once the job completes.

<Steps>
<Step title="Start a static export job">
Call [Start static export job](/api/static-export/start-job) with the domain you want to export. The API queues the job and returns a `jobId`.
</Step>
<Step title="Query the job status">
Poll [Get static export job status](/api/static-export/get-job-status) with the `jobId` until `status` is `completed`. The response includes live `progress` and `pageCount` while the job runs.
</Step>
<Step title="Generate the bundle">
Call [Generate export bundle](/api/static-export/generate-bundle) with the `jobId`. The API packages the export into a single archive and returns `bundleUrl`, a presigned S3 link to the static export bundle. Download it before the link expires.
</Step>
</Steps>

## Feature support by deployment

Which features are available depends on how you host your deployment. Air-gapped deployments have no outbound network access, so anything that relies on Mintlify's cloud services is unavailable. Features labeled **Configurable** have different availability depending on your environment's setup.

| Feature | Cloud | Client-hosted | Air-gapped |
| --- | :---: | :---: | :---: |
| Documentation search | <Icon icon="check" color="#16a34a" /> | Configurable | <Icon icon="x" color="#dc2626" /> |
| AI assistant | <Icon icon="check" color="#16a34a" /> | Configurable | <Icon icon="x" color="#dc2626" /> |
| Web analytics | <Icon icon="check" color="#16a34a" /> | Configurable | <Icon icon="x" color="#dc2626" /> |
| API playground ("Try it") | <Icon icon="check" color="#16a34a" /> | <Icon icon="check" color="#16a34a" /> | Configurable |
| Static export bundle | <Icon icon="check" color="#16a34a" /> | <Icon icon="check" color="#16a34a" /> | <Icon icon="check" color="#16a34a" /> |

## Endpoints

Check warning on line 41 in api/static-export/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/static-export/overview.mdx#L41

Use 'endpoints?' instead of 'Endpoints'.

- [Start static export job](/api/static-export/start-job): Start a static export job for a deployment.
- [Get static export job status](/api/static-export/get-job-status): Poll the status and progress of a running job.
- [Generate export bundle](/api/static-export/generate-bundle): Package a completed job and return a single S3 link to the bundle.

## Authentication

Authenticate requests with your admin API key. Generate an admin API key on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Admin API keys begin with the `mint_` prefix and are server-side secrets--do not expose them in client-side code.

## Deploy the bundle to your Enterprise Helm chart

Check warning on line 51 in api/static-export/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/static-export/overview.mdx#L51

'Deploy the bundle to your Enterprise Helm chart' should use sentence-style capitalization.

Self-hosted Mintlify is deployed with the Helm chart in the [`mintlify/enterprise`](https://github.com/mintlify/enterprise) repository. Once a static export job produces a bundle, you point the chart at the bundle and the deployment serves it from your own infrastructure.

Check warning on line 53 in api/static-export/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/static-export/overview.mdx#L53

In general, use active voice instead of passive voice ('is deployed').

<Steps>
<Step title="Add the bundle reference to your values">
Set the static export fields in your `values.yaml` to the `bundleUrl` returned by [Generate export bundle](/api/static-export/generate-bundle). The chart fetches the bundle on startup and serves it as the active version.

```yaml 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"
```
</Step>
<Step title="Roll out the chart">
Apply the updated values with a `helm upgrade`. The deployment downloads the bundle, swaps it in as the live site, and serves it from your cluster.

```bash
helm upgrade --install mintlify mintlify/enterprise \
--namespace mintlify \
--create-namespace \
-f values.yaml
```
</Step>
</Steps>

Because presigned links expire, regenerate the bundle and re-run the upgrade whenever you publish new content or automate the loop with GitHub Actions.

## Automate with a GitHub Action

The following template workflow runs the full export loop on a schedule or on demand. It starts a job, polls until the export completes, generates a bundle, and rolls the new `bundleUrl` into the Helm chart.

```yaml .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
Comment thread
cursor[bot] marked this conversation as resolved.
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 }}"
```

Store your admin API key as the `MINTLIFY_ADMIN_KEY` repository secret, and configure cluster credentials (for example, with `azure/setup-helm` and your kubeconfig) before the deploy step.

Check warning on line 136 in api/static-export/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/static-export/overview.mdx#L136

Did you really mean 'kubeconfig'?
10 changes: 10 additions & 0 deletions api/static-export/start-job.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: "Start static export job"
openapi: "/static-export-openapi.json POST /static-export/jobs"

Check warning on line 3 in api/static-export/start-job.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api/static-export/start-job.mdx#L3

Use 'JSON' instead of 'json'.
keywords: ["static export", "job", "start", "bundle", "enterprise"]
---

<Info>
Static export requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-export).
</Info>

12 changes: 11 additions & 1 deletion docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,8 @@
"guides/developer-documentation",
"guides/knowledge-base",
"guides/help-center",
"guides/custom-frontend"
"guides/custom-frontend",
"api/static-export/overview"
]
}
]
Expand Down Expand Up @@ -413,6 +414,15 @@
"api/analytics/views",
"api/analytics/visitors"
]
},
{
"group": "Static export",
"icon": "package",
"pages": [
"api/static-export/start-job",
"api/static-export/get-job-status",
"api/static-export/generate-bundle"
]
}
]
},
Expand Down
Loading
Loading