docs(deploy): document root mintlify proxy paths

deploy/cloudflare.mdx

@@ -101,7 +101,7 @@
 ```
 
 <Warning>
-  In addition to your subpath, your Worker must proxy `/mintlify-assets/*`, which serves the CSS, JavaScript, and favicons for your documentation, and `/_mintlify/*`, which handles requests for core site functionality.
+  In addition to your subpath, your Worker must proxy `/_mintlify/*` and `/mintlify-assets/*`. These paths serve the CSS, JavaScript, fonts, favicons, and API requests for your documentation. Without them, pages load without styles.
 
   If you route traffic to your Worker with route patterns instead of a custom domain, add routes for `yoursite.com/mintlify-assets/*` and `yoursite.com/_mintlify/*` alongside your subpath route. These paths must originate from the root of your domain, not your subpath.
 </Warning>
@@ -214,9 +214,10 @@
 
 ### Symptoms
 
+- Pages load without styles because requests for CSS and JavaScript files are blocked.
 - 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.
+- 403 errors in the browser console for requests to `/_mintlify/*` or `/mintlify-assets/*` paths.
 - Cloudflare security challenge messages about "malformed data" or "suspicious URL patterns."
 
 ### Root cause
@@ -249,6 +250,11 @@
 **And:**
 - Field: `URI Path`
 - Operator: `starts with`
+- Value: `/_mintlify/`
+
+**Or:**
+- Field: `URI Path`
+- Operator: `starts with`
 - Value: `/mintlify-assets/`
 
 **Then:**
@@ -297,7 +303,7 @@
 Status: Enabled
 
 When incoming requests match:
-  (http.host eq "docs.yourdomain.com" and starts_with(http.request.uri.path, "/mintlify-assets/"))
+  (http.host eq "docs.yourdomain.com" and (starts_with(http.request.uri.path, "/_mintlify/") or starts_with(http.request.uri.path, "/mintlify-assets/")))
 
 Then:
   Skip: All remaining custom rules, Managed rules, Super Bot Fight Mode

deploy/docs-subpath.mdx

@@ -15,7 +15,7 @@ Only use this option if Mintlify can receive all paths on the domain.
 
 ## Set up by hosting provider
 
-If another site runs on your domain, configure your hosting provider to proxy your subpath to Mintlify. Select your hosting provider and follow the setup instructions.
+If another site runs on your domain, configure your hosting provider to proxy your subpath to Mintlify. Also proxy `/_mintlify/*` and `/mintlify-assets/*` from the root of your domain. Mintlify can serve your site's CSS, JavaScript, and API requests from these paths, so pages load without styles if you only proxy your subpath. Select your hosting provider and follow the setup instructions.
 
 - [Cloudflare](/deploy/cloudflare): Set up Cloudflare Workers for your domain to serve your documentation at your subpath.
 - [AWS Route 53 and CloudFront](/deploy/route53-cloudfront): Deploy your documentation at your subpath using AWS with Route 53 DNS and CloudFront CDN.

deploy/reverse-proxy.mdx

@@ -43,14 +43,22 @@
 | `/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 |
+| `/_mintlify/*`                    | `<your-subdomain>.mintlify.site/_mintlify/*` | Use origin headers |
+| `/mintlify-assets/*`              | `<your-subdomain>.mintlify.site/mintlify-assets/*` | Use origin headers |
 | `/.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.
+<Warning>
+  Proxy `/_mintlify/*` and `/mintlify-assets/*` from the root of your domain, not from under your base path. Mintlify can serve your site's CSS, JavaScript, fonts, favicons, and API requests from root paths like `/_mintlify/assets/*`. If your proxy only forwards your base path, pages load without styles or interactivity.
+</Warning>
+
+Mintlify sets cache headers on `/_mintlify/*` and `/mintlify-assets/*` responses. Versioned files under `/_mintlify/assets/*` are safe to cache long term, and API responses are marked as uncacheable. Pass these headers through instead of setting your own caching rules for these paths. Some sites don't request `/mintlify-assets/*`, but forwarding it is harmless.
+
+Your proxy must forward all HTTP methods on documentation and `/_mintlify/*` paths. Mintlify sends analytics events and API playground requests as `POST` requests to `/_mintlify/api/*` paths. 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.
 
@@ -152,6 +160,26 @@
         add_header Cache-Control "no-cache, no-store, must-revalidate";
     }
 
+    # Mintlify assets and API routes, served from the root of your domain.
+    # Keep the cache headers Mintlify sends so browsers cache hashed assets.
+    location ^~ /_mintlify/ {
+        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;
+    }
+
+    location ^~ /mintlify-assets/ {
+        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;
+    }
+
     # Documentation root
     location = /docs {
         proxy_pass https://<your-subdomain>.mintlify.site;
@@ -188,6 +216,8 @@
 
 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.
 
+Do not add your base path to the `/_mintlify/*` and `/mintlify-assets/*` routes. With a custom base path, Mintlify serves these files only from the root, so `<your-subdomain>.mintlify.site/<your-base-path>/_mintlify/*` returns a 404.
+
 ## Troubleshooting
 
 ### Changes not appearing
@@ -198,6 +228,14 @@
 
 **Solution**: Update your reverse proxy configuration to point to `<your-subdomain>.mintlify.site`.
 
+### Pages load without styles
+
+**Symptoms**: Pages render as unstyled HTML. The browser console shows 404 errors for `/_mintlify/assets/*` or `/mintlify-assets/*` files.
+
+**Cause**: Your proxy forwards your base path but not the root `/_mintlify/*` and `/mintlify-assets/*` paths.
+
+**Solution**: Add routes for `/_mintlify/*` and `/mintlify-assets/*` at the root of your domain that point to `<your-subdomain>.mintlify.site`. See [Routing configuration](#routing-configuration).
+
 ### 404 error
 
 **Symptoms**: Documentation loads, but features don't work. API calls fail.
@@ -227,4 +265,4 @@
 
 **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.
+**Solution**: Disable caching for documentation paths. For `/_mintlify/*` and `/mintlify-assets/*`, pass through the cache headers Mintlify sends instead of overriding them.

deploy/route53-cloudfront.mdx

@@ -26,11 +26,14 @@
 - `/.well-known/vercel/*` - Required for domain verification
 - `/docs/*` - Required for subpath routing
 - `/docs` - Required for subpath routing
-- `/_mintlify/*` - Required for core site functionality
 
-Route traffic to these paths with a Cache Policy of **CachingOptimized**:
+Route traffic to these paths with a Cache Policy of **UseOriginCacheControlHeaders-QueryStrings**, so CloudFront follows the cache headers Mintlify sends:
+
+- `/_mintlify/*` - Required for CSS, JavaScript, fonts, and API requests
+- `/mintlify-assets/*` - Required for favicons and static assets on some sites
+
+Route traffic to this path with a Cache Policy of **CachingOptimized**:
 
-- `/mintlify-assets/*` - Required for CSS, JavaScript, and favicons
 - `Default (*)` - Your website's landing page
 
 All Behaviors must have an **origin request policy** of `AllViewerExceptHostHeader`.
@@ -116,17 +119,17 @@
 
 ### `/mintlify-assets/*`
 
-Create a behavior with a **Path pattern** of `/mintlify-assets/*` and set **Origin and origin groups** to the `.mintlify.site` URL. This path serves the CSS, JavaScript, and favicons for your documentation from the root of your domain.
+Create a behavior with a **Path pattern** of `/mintlify-assets/*` and set **Origin and origin groups** to the `.mintlify.site` URL. This path serves favicons and static assets for some documentation sites from the root of your domain.
 
- - Set "Cache policy" to **CachingOptimized**.
+ - Set "Cache policy" to **UseOriginCacheControlHeaders-QueryStrings**.
  - Set "Origin request policy" to **AllViewerExceptHostHeader**.
  - Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**.
 
 ### `/_mintlify/*`
 
-Create a behavior with a **Path pattern** of `/_mintlify/*` and set **Origin and origin groups** to the `.mintlify.site` URL. This path handles requests from the root of your domain for core site functionality.
+Create a behavior with a **Path pattern** of `/_mintlify/*` and set **Origin and origin groups** to the `.mintlify.site` URL. This path serves the CSS, JavaScript, fonts, and API requests for your documentation from the root of your domain. Without this behavior, pages load without styles.
 
-- Set "Cache policy" to **CachingDisabled**.
+- Set "Cache policy" to **UseOriginCacheControlHeaders-QueryStrings**. Mintlify marks versioned assets as cacheable and API responses as uncacheable.
 - Set "Origin request policy" to **AllViewerExceptHostHeader**.
 - Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**.
 - Set "Allowed HTTP methods" to **GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE**.

deploy/vercel.mdx

@@ -63,7 +63,7 @@
 - **`destination`**: Where the request should be proxied to.
 - **`:match*`**: A wildcard that captures any path segments after your subpath.
 
-The `/_mintlify` rewrite is required for core site functionality. The `/mintlify-assets` rewrite is required for static assets.
+The `/_mintlify` rewrite is required. It serves your site's CSS, JavaScript, fonts, and API requests from the root of your domain. Without it, pages load without styles. The `/mintlify-assets` rewrite serves favicons and static assets for some sites. Keep both rewrites at the root of your domain, without your subpath.
 
 For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation.
 
@@ -93,7 +93,8 @@
 
 - `/.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.
+- `/_mintlify/*`: Required for CSS, JavaScript, fonts, and API requests.
+- `/mintlify-assets/*`: Required for favicons and static assets on some sites.
 
 Your proxy should pass these paths directly to your Vercel deployment without modification.