mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
f66b301e00
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
231 lines
11 KiB
Plaintext
231 lines
11 KiB
Plaintext
---
|
|
title: "Reverse proxy"
|
|
description: "Configure a custom reverse proxy with nginx or a similar tool to serve your Mintlify documentation at a subpath on your own domain."
|
|
keywords: ["reverse proxy configuration","nginx","proxy routing","header forwarding"]
|
|
---
|
|
|
|
import SubpathSetupSteps from "/snippets/subpath-setup-steps.mdx";
|
|
|
|
To serve your documentation through a custom reverse proxy, you must configure routing rules, caching policies, and header forwarding.
|
|
|
|
When you implement a reverse proxy, monitor for potential issues with domain verification, SSL certificate provisioning, authentication flows, performance, and analytics tracking.
|
|
|
|
## Set your base path
|
|
|
|
Set your base path on the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. Then configure your reverse proxy to route that path to Mintlify. The default base path is `/docs`, but you can use any base path you choose, like `/help` or `/resources`.
|
|
|
|
The directory that contains your documentation in your repository does not configure the public base path. For example, storing documentation under a `/docs` directory does not replace setting `/docs` as the base path in your dashboard.
|
|
|
|
In all configurations, use `mintlify.site` as the proxy target.
|
|
|
|
## Host at `/docs` subpath
|
|
|
|
Use this configuration when you want to serve documentation at the `/docs` path on your domain.
|
|
|
|
Before configuring your reverse proxy:
|
|
|
|
1. Navigate to [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) in your dashboard.
|
|
2. Enable the **Host at** toggle.
|
|
3. Enter your domain.
|
|
4. Enter `docs` as your base path.
|
|
5. Click **Add domain**.
|
|
|
|
<Warning>
|
|
When you host at a subpath, your canonical docs URL becomes `<your-subdomain>.mintlify.site<your-base-path>`, like `<your-subdomain>.mintlify.site/docs`. Proxy to `<your-subdomain>.mintlify.site` so cache invalidation and updates take effect.
|
|
</Warning>
|
|
|
|
### Routing configuration
|
|
|
|
Proxy these paths to your Mintlify subdomain:
|
|
|
|
| Path | Destination | Caching |
|
|
| --------------------------------- | ------------------------------------ | -------- |
|
|
| `/docs` | `<your-subdomain>.mintlify.site/docs` | No cache |
|
|
| `/docs/*` | `<your-subdomain>.mintlify.site/docs/*` | No cache |
|
|
| `/docs/_llms/*` | `<your-subdomain>.mintlify.site/docs/_llms/*` | No cache |
|
|
| `/.well-known/vercel/*` | `<your-subdomain>.mintlify.site/.well-known/vercel/*` | No cache |
|
|
| `/.well-known/skills/*` (optional) | `<your-subdomain>.mintlify.site/docs/.well-known/skills/*` | No cache |
|
|
| `/.well-known/agent-skills/*` (optional) | `<your-subdomain>.mintlify.site/docs/.well-known/agent-skills/*` | No cache |
|
|
| `/skill.md` (optional) | `<your-subdomain>.mintlify.site/docs/skill.md` | No cache |
|
|
| `/llms.txt` (optional) | `<your-subdomain>.mintlify.site/docs/llms.txt` | No cache |
|
|
| `/llms-full.txt` (optional) | `<your-subdomain>.mintlify.site/docs/llms-full.txt` | No cache |
|
|
|
|
Your proxy must forward all HTTP methods on documentation paths. Mintlify sends analytics events as `POST` requests to `/docs/_mintlify/api/v1/e`. A proxy that only allows `GET` and `HEAD` requests silently breaks the analytics in your dashboard.
|
|
|
|
Mintlify serves these files under your base path, like `<your-subdomain>.mintlify.site/docs/llms.txt`. They are available on your domain under your subpath, like `your-domain.com/docs/llms.txt`, through your main subpath route.
|
|
|
|
The `/docs/*` route also covers generated `llms.txt` indexes under `/docs/_llms/*`. If your proxy uses a more granular path allowlist instead of forwarding all `/docs/*` requests, include `/docs/_llms/*` so agents can follow every index linked from `/docs/llms.txt`.
|
|
|
|
Do not rewrite only `/docs/llms.txt` to a root-hosted `/llms.txt`. Set `/docs` as the deployment base path and forward the full `/docs/*` route. This keeps page links and generated `/docs/_llms/*` index links on the same public prefix.
|
|
|
|
The `/.well-known/skills/*`, `/.well-known/agent-skills/*`, `/skill.md`, `/llms.txt`, and `/llms-full.txt` routes are optional. Include them only if you also want to serve these files at root paths on your domain, like `your-domain.com/llms.txt`. Each root path maps to the file under your base path on your Mintlify subdomain.
|
|
|
|
### Required header configuration
|
|
|
|
Configure your reverse proxy with these header requirements:
|
|
|
|
- **Origin**: Contains the target subdomain `<your-subdomain>.mintlify.site`.
|
|
- **X-Forwarded-For**: Preserves client IP information.
|
|
- **X-Forwarded-Proto**: Preserves the original protocol (HTTP/HTTPS).
|
|
- **X-Real-IP**: Forwards the real client IP address.
|
|
- **User-Agent**: Forwards the user agent.
|
|
|
|
<Warning>
|
|
Do not forward the `Host` header.
|
|
</Warning>
|
|
|
|
### Example nginx configuration
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name <your-domain>.com;
|
|
|
|
# Vercel verification paths
|
|
location ~ ^/\.well-known/vercel/ {
|
|
proxy_pass https://<your-subdomain>.mintlify.site;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
|
|
# AI skills paths
|
|
location ^~ /.well-known/skills/ {
|
|
proxy_pass https://<your-subdomain>.mintlify.site/docs/.well-known/skills/;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
|
|
# Agent-skills discovery paths
|
|
location ^~ /.well-known/agent-skills/ {
|
|
proxy_pass https://<your-subdomain>.mintlify.site/docs/.well-known/agent-skills/;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
|
|
# Skill manifest (optional)
|
|
location = /skill.md {
|
|
proxy_pass https://<your-subdomain>.mintlify.site/docs/skill.md;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
|
|
# LLM index files (optional)
|
|
location = /llms.txt {
|
|
proxy_pass https://<your-subdomain>.mintlify.site/docs/llms.txt;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
|
|
location = /llms-full.txt {
|
|
proxy_pass https://<your-subdomain>.mintlify.site/docs/llms-full.txt;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
|
|
# Documentation root
|
|
location = /docs {
|
|
proxy_pass https://<your-subdomain>.mintlify.site;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
|
|
# All documentation paths
|
|
location /docs/ {
|
|
proxy_pass https://<your-subdomain>.mintlify.site/docs/;
|
|
proxy_set_header Origin <your-subdomain>.mintlify.site;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header User-Agent $http_user_agent;
|
|
|
|
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
|
}
|
|
}
|
|
```
|
|
|
|
## Custom subpath
|
|
|
|
To use a subpath other than `/docs` (such as `/help` or `/resources`):
|
|
|
|
<SubpathSetupSteps />
|
|
|
|
Mintlify rebuilds your documentation to serve at your base path, so `<your-subdomain>.mintlify.site<your-base-path>` serves your content.
|
|
|
|
Configure your reverse proxy using the same [routing configuration](#routing-configuration), [header requirements](#required-header-configuration), and nginx patterns as the `/docs` subpath, replacing `/docs` with your base path.
|
|
|
|
## Troubleshooting
|
|
|
|
### Changes not appearing
|
|
|
|
**Symptoms**: You publish documentation updates, but the changes don't appear on your site.
|
|
|
|
**Cause**: Your reverse proxy points to an outdated hostname.
|
|
|
|
**Solution**: Update your reverse proxy configuration to point to `<your-subdomain>.mintlify.site`.
|
|
|
|
### 404 error
|
|
|
|
**Symptoms**: Documentation loads, but features don't work. API calls fail.
|
|
|
|
**Cause**: The reverse proxy forwards the `Host` header or the `Origin` header is missing.
|
|
|
|
**Solution**:
|
|
|
|
- Remove `Host` header forwarding.
|
|
- Set the `Origin` header to your Mintlify subdomain (`<your-subdomain>.mintlify.site`).
|
|
|
|
### Generated `/_llms/` links return 404
|
|
|
|
**Symptoms**: Your `llms.txt` file loads, but links under `/_llms/` return 404 or omit your public subpath.
|
|
|
|
**Cause**: The public subpath does not match the base path configured in Mintlify, or the proxy only forwards `llms.txt` and not its generated index routes.
|
|
|
|
**Solution**:
|
|
|
|
- Set the public subpath as the base path in your Mintlify dashboard. A repository directory with the same name does not configure it.
|
|
- Forward the full `<base-path>/*` route, or add `<base-path>/_llms/*` to a granular allowlist.
|
|
- Redeploy your documentation, then verify both `<base-path>/llms.txt` and one linked `<base-path>/_llms/*.md` URL.
|
|
|
|
### Performance issues
|
|
|
|
**Symptoms**: Slow page loads and layout shifts.
|
|
|
|
**Cause**: Incorrect caching configuration.
|
|
|
|
**Solution**: Disable caching for documentation paths. If you proxy `/mintlify-assets/_next/static/*` paths, enable caching only for those static assets.
|