From e795d7a07cc601f5a24ed271e7a34f99d7705540 Mon Sep 17 00:00:00 2001 From: Alejandro Cortez Date: Tue, 21 Jul 2026 12:43:20 -0400 Subject: [PATCH 1/2] Document /mintlify-assets and /_mintlify routing for subpath proxies Co-Authored-By: Claude Fable 5 --- deploy/cloudflare.mdx | 20 ++++++++++++++++---- deploy/route53-cloudfront.mdx | 16 ++++++++++++++-- 2 files changed, 30 insertions(+), 6 deletions(-) diff --git a/deploy/cloudflare.mdx b/deploy/cloudflare.mdx index 257a9ad7f4..e89641d294 100644 --- a/deploy/cloudflare.mdx +++ b/deploy/cloudflare.mdx @@ -70,8 +70,12 @@ async function handleRequest(request) { return await fetch(request); } - // If the request is to the docs subpath - if (/^\/docs/.test(urlObject.pathname)) { + // If the request is to the docs subpath or a Mintlify asset or API path + if ( + /^\/docs/.test(urlObject.pathname) || + /^\/mintlify-assets\//.test(urlObject.pathname) || + /^\/_mintlify\//.test(urlObject.pathname) + ) { // Then Proxy to Mintlify const DOCS_URL = "[SUBDOMAIN].mintlify.site"; const CUSTOM_URL = "[YOUR_DOMAIN]"; @@ -96,6 +100,10 @@ async function handleRequest(request) { } ``` + + 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 API playground requests. These paths are requested from the root of your domain, not your subpath. 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. + + Click **Deploy** and wait for the changes to propagate. @@ -154,8 +162,12 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d return await fetch(request); } - // If the request is to the docs subpath - if (/^\/docs/.test(urlObject.pathname)) { + // If the request is to the docs subpath or a Mintlify asset or API path + if ( + /^\/docs/.test(urlObject.pathname) || + /^\/mintlify-assets\//.test(urlObject.pathname) || + /^\/_mintlify\//.test(urlObject.pathname) + ) { // Proxy to Mintlify const DOCS_URL = "[SUBDOMAIN].mintlify.site"; const CUSTOM_URL = "[YOUR_DOMAIN]"; diff --git a/deploy/route53-cloudfront.mdx b/deploy/route53-cloudfront.mdx index 86db9fcfcc..29da777676 100644 --- a/deploy/route53-cloudfront.mdx +++ b/deploy/route53-cloudfront.mdx @@ -26,10 +26,11 @@ Route traffic to these paths with a Cache Policy of **CachingDisabled**: - `/.well-known/vercel/*` - Required for domain verification - `/docs/*` - Required for subpath routing - `/docs/` - Required for subpath routing +- `/_mintlify/*` - Required for API playground requests Route traffic to these paths with a Cache Policy of **CachingEnabled**: -- `/mintlify-assets/_next/static/*` +- `/mintlify-assets/*` - Required for CSS, JavaScript, and favicons - `Default (*)` - Your website's landing page All Behaviors must have an **origin request policy** of `AllViewerExceptHostHeader`. @@ -155,12 +156,23 @@ These settings should exactly match your base subpath behavior, with the excepti - Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**. - Set "Allowed HTTP methods" to **GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE**. -### `/mintlify-assets/_next/static/*` +### `/mintlify-assets/*` + +Create a behavior with a **Path pattern** of `/mintlify-assets/*` with **Origin and origin groups** pointing to the `.mintlify.site` URL. This path serves the CSS, JavaScript, and favicons for your documentation from the root of your domain. - Set "Cache policy" to **CachingOptimized**. - 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/*` with **Origin and origin groups** pointing to the `.mintlify.site` URL. This path handles API playground requests from the root of your domain. + +- Set "Cache policy" to **CachingDisabled**. +- 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**. + ### `Default (*)` Edit the `Default (*)` behavior. From 936226a90c699af9b5b0b9e97ec4c620d1211c80 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 23 Jul 2026 09:32:53 -0700 Subject: [PATCH 2/2] Update deploy/cloudflare.mdx --- deploy/cloudflare.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/deploy/cloudflare.mdx b/deploy/cloudflare.mdx index e89641d294..3c5c01d057 100644 --- a/deploy/cloudflare.mdx +++ b/deploy/cloudflare.mdx @@ -101,7 +101,9 @@ async function handleRequest(request) { ``` - 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 API playground requests. These paths are requested from the root of your domain, not your subpath. 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. + 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 API playground requests. + + 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. Click **Deploy** and wait for the changes to propagate.