diff --git a/deploy/cloudflare-firewall-troubleshooting.mdx b/deploy/cloudflare-firewall-troubleshooting.mdx index 562beb83f..069e36be7 100644 --- a/deploy/cloudflare-firewall-troubleshooting.mdx +++ b/deploy/cloudflare-firewall-troubleshooting.mdx @@ -8,18 +8,18 @@ If your documentation site shows 500 errors after a few seconds or experiences s ## Symptoms -- Documentation page loads initially but crashes with a 500 error after 30-60 seconds -- Slow or broken client-side navigation between pages -- 403 errors in browser console for requests to `/mintlify-assets/*` paths -- Cloudflare security challenge messages about "malformed data" or "suspicious URL patterns" +- Documentation page loads initially but crashes with a 500 error after 30-60 seconds. +- Slow or broken client-side navigation between pages. +- 403 errors in the browser console for requests to `/mintlify-assets/*` paths. +- Cloudflare security challenge messages about "malformed data" or "suspicious URL patterns". ## Root cause Cloudflare's Web Application Firewall (WAF) and Bot Fight Mode can flag Mintlify asset requests as suspicious due to: -- Multiple `%` symbols in encoded URL parameters -- Long query strings with special characters -- Automated requests from idle tabs +- Multiple `%` symbols in encoded URL parameters. +- Long query strings with special characters. +- Automated requests from idle tabs. ## Solution @@ -27,10 +27,10 @@ Create a Cloudflare firewall rule to exempt Mintlify assets from security checks ### Create the firewall exception -1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com/) -2. Select your domain -3. Navigate to **Security > WAF** -4. Click **Create rule** +1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com/). +2. Select your domain. +3. Navigate to **Security > WAF**. +4. Click **Create rule**. 5. Configure the rule with these settings: **Rule name:** Allow Mintlify assets @@ -49,40 +49,40 @@ Create a Cloudflare firewall rule to exempt Mintlify assets from security checks - Action: `Skip` - Select: `All remaining custom rules`, `Managed rules`, and `Super Bot Fight Mode` -6. Enable **Log** to track matched requests -7. Click **Deploy** +6. Enable **Log** to track matched requests. +7. Click **Deploy**. ### Verify the rule After deploying: -1. Open your documentation site in a browser -2. Leave the page idle for 2-3 minutes -3. Navigate between pages -4. Check browser console for any 403 errors +1. Open your documentation site in a browser. +2. Leave the page idle for 2-3 minutes. +3. Navigate between pages. +4. Check the browser console for any 403 errors. If issues persist, verify your rule configuration: -- Ensure the hostname exactly matches your docs domain -- Confirm the URI path uses `starts with` (not `contains`) -- Do not include wildcards (`*`) in the path value -- Verify that you enabled and deployed the rule +- Ensure the hostname exactly matches your docs domain. +- Confirm the URI path uses `starts with` (not `contains`). +- Do not include wildcards (`*`) in the path value. +- Verify that you enabled and deployed the rule. ## Common mistakes -- Using `contains` operator with `/mintlify-assets/*` - The `*` is treated as a literal character, not a wildcard -- Using `equals` for URI Path - This only matches the exact path `/mintlify-assets/` and not subpaths -- Forgetting to skip Bot Fight Mode - This must be explicitly included in the skip action -- Wrong hostname - Must match your actual documentation domain +- Using the `contains` operator with `/mintlify-assets/*`. The `*` is treated as a literal character, not a wildcard. +- Using `equals` for URI Path. This only matches the exact path `/mintlify-assets/` and not subpaths. +- Forgetting to skip Bot Fight Mode. Explicitly include it in the skip action. +- Setting the wrong hostname. It must match your actual documentation domain. ## Additional troubleshooting If the firewall exception doesn't resolve the issue: -1. Check Cloudflare's **Security > Events** log for blocked requests -2. Verify your Cloudflare Worker (if using a custom subpath) sets the `Host` header to your `.mintlify.site` target instead of passing through the original request's `Host` header -3. Temporarily set Security Level to "Essentially Off" to confirm Cloudflare is the cause -4. Review any custom Page Rules that might override the firewall exception +1. Check Cloudflare's **Security > Events** log for blocked requests. +2. Verify that your Cloudflare Worker (if using a custom subpath) sets the `Host` header to your `.mintlify.site` target instead of passing through the original request's `Host` header. +3. Temporarily set Security Level to "Essentially Off" to confirm that Cloudflare is the cause. +4. Review any custom Page Rules that might override the firewall exception. ## Example working configuration diff --git a/deploy/cloudflare.mdx b/deploy/cloudflare.mdx index f366e65ff..05ec4a78c 100644 --- a/deploy/cloudflare.mdx +++ b/deploy/cloudflare.mdx @@ -39,8 +39,8 @@ Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt Your Cloudflare Worker must allow traffic to these specific paths without blocking or redirecting: -- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification -- `/.well-known/vercel/*` - Required for Vercel domain verification +- `/.well-known/acme-challenge/*`: Required for Let's Encrypt certificate verification. +- `/.well-known/vercel/*`: Required for Vercel domain verification. While Cloudflare automatically handles many verification rules, creating additional custom rules may inadvertently block this critical traffic. @@ -117,17 +117,17 @@ After your code deploys, test your Worker to ensure it routes to your Mintlify d 1. Test using the Worker's preview URL: `your-worker.your-subdomain.workers.dev/docs` 2. Verify the Worker routes to your Mintlify docs and your website. -### Add custom domain +### Add a custom domain 1. In your [Cloudflare dashboard](https://dash.cloudflare.com/), navigate to your Worker. 2. Go to **Settings > Domains & Routes > Add > Custom Domain**. -3. Add your domain. +3. Add your domain. Add your domain both with and without `www.` prepended. -See [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) in the Cloudflare documentation for more information. +See [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) in the Cloudflare documentation for more information. ### Resolve DNS conflicts diff --git a/deploy/custom-portal.mdx b/deploy/custom-portal.mdx index 3b67b378f..58d69d68d 100644 --- a/deploy/custom-portal.mdx +++ b/deploy/custom-portal.mdx @@ -8,7 +8,7 @@ keywords: ["developer portal", "custom presentation layer", "API marketplace", " Custom portals require an [Enterprise plan](https://mintlify.com/pricing?ref=custom-portal) and a [self-hosted deployment](/deploy/self-host). Reach out to your account team to scope one. -For some platforms, documentation is one surface of a larger product—an API marketplace, a partner portal, or a developer experience with sign-in, credentials, and support built in. Mintlify supports those use cases by designing, building, and maintaining a custom presentation layer that replaces your existing portal front end, while your team authors content through the Mintlify editor or a Git-backed workflow. +For some platforms, documentation is one surface of a larger product—an API marketplace, a partner portal, or a developer experience with sign-in, credentials, and support built in. Mintlify supports those use cases by designing, building, and maintaining a custom presentation layer that replaces your existing portal front end, while your team authors content through the Mintlify editor or a Git-backed workflow. The portal integrates with your existing APIs, gateway, and downstream systems, which remain owned and operated by your team. @@ -62,7 +62,7 @@ The custom presentation layer and Mintlify platform run inside your network boun Sign-in, credential management, subscriptions, and other logged-in experiences follow, integrated with your identity provider and backend APIs. - Login-aware search and server-side personalization complete the core experience. Optional AI features remain disabled disabled until your security or AI governance team approves them. + Login-aware search and server-side personalization complete the core experience. Optional AI features remain disabled until your security or AI governance team approves them. diff --git a/deploy/reverse-proxy.mdx b/deploy/reverse-proxy.mdx index ef83a22e9..4e0dc7239 100644 --- a/deploy/reverse-proxy.mdx +++ b/deploy/reverse-proxy.mdx @@ -57,14 +57,14 @@ The `/.well-known/skills/*`, `/.well-known/agent-skills/*`, `/skill.md`, `/llms. Configure your reverse proxy with these header requirements: -- **Origin**: Contains the target subdomain `.mintlify.site` -- **X-Forwarded-For**: Preserves client IP information -- **X-Forwarded-Proto**: Preserves original protocol (HTTP/HTTPS) -- **X-Real-IP**: Forwards the real client IP address -- **User-Agent**: Forwards the user agent +- **Origin**: Contains the target 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. - Ensure that the `Host` header is not forwarded. + Do not forward the `Host` header. ### Example nginx configuration @@ -199,8 +199,8 @@ Configure your reverse proxy using the same [routing configuration](#routing-con **Solution**: -- Remove `Host` header forwarding -- Set the `Origin` header to your Mintlify subdomain (`.mintlify.site`) +- Remove `Host` header forwarding. +- Set the `Origin` header to your Mintlify subdomain (`.mintlify.site`). ### Performance issues diff --git a/deploy/vercel-external-proxies.mdx b/deploy/vercel-external-proxies.mdx index 3314fe2b4..193b56a46 100644 --- a/deploy/vercel-external-proxies.mdx +++ b/deploy/vercel-external-proxies.mdx @@ -14,15 +14,15 @@ See the [supported providers](https://vercel.com/guides/how-to-setup-verified-pr Your external proxy must allow traffic to these specific paths without blocking, redirecting, or heavily caching: -- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification -- `/.well-known/vercel/*` - Required for Vercel domain verification -- `/mintlify-assets/_next/static/*` - Required for static assets +- `/.well-known/acme-challenge/*`: Required for Let's Encrypt certificate verification. +- `/.well-known/vercel/*`: Required for Vercel domain verification. +- `/mintlify-assets/_next/static/*`: Required for static assets. These paths should pass through directly to your Vercel deployment without modification. ## Header forwarding requirements -Ensure that your proxy correctly forwards the `HOST` header. Without proper header forwarding, verification requests fail. +Ensure that your proxy correctly forwards the `Host` header. Without proper header forwarding, verification requests fail. ## Test your proxy setup