-
Notifications
You must be signed in to change notification settings - Fork 235
added copy for client export feature #6300
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
8571017
added copy for client export feature
chitalian ce93fd8
Fail GitHub Action when export job times out
chitalian 30a1159
update availability callouts
ethanpalm aa7c5f5
Merge branch 'justin/client-exports' of https://github.com/mintlify/d…
ethanpalm 393d957
add missing 400
ethanpalm cc1a770
💅
ethanpalm File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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" | ||
| keywords: ["static export", "bundle", "s3", "download", "enterprise"] | ||
| --- | ||
|
|
||
| <Info> | ||
| Static export requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-export). | ||
| </Info> | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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}" | ||
| keywords: ["static export", "job", "status", "progress", "enterprise"] | ||
| --- | ||
|
|
||
| <Info> | ||
| Static export requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-export). | ||
| </Info> | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
|
|
||
| - [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 | ||
|
|
||
| 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. | ||
|
|
||
| <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 | ||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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" | ||
| keywords: ["static export", "job", "start", "bundle", "enterprise"] | ||
| --- | ||
|
|
||
| <Info> | ||
| Static export requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-export). | ||
| </Info> | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.