diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index f290c289..ef0d889d 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -5,80 +5,146 @@ description: "Host documentation at a /docs subpath using Cloudflare Workers" ## Create Cloudflare Worker -Navigate to the `Workers & Pages > Create application > Create worker`. You -should be presented with the following screen where you can create a new -Cloudflare worker. +1. In Cloudflare, navigate to the **Create an application** page in the **Workers & Pages** settings. +2. Select **Create worker**. - Create a Cloudflare worker +The Cloudflare Workers & Pages settings page with the Create Worker button emphasized. - - Keep in mind: If your DNS provider is Cloudflare you should not use proxying for the CNAME record - - -### Add custom domain - -Once the worker is created, click `Configure worker`. Navigate to the worker -`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain -into the list - we recommend you add both the version with and without `www.` -prepended to the domain. +## Add custom domain + +1. Select **Configure Worker**. +2. Navigate to **Triggers** section of the Settings tab. +3. Select **Add Custom Domain**. +4. Add your domain to the list. We recommend that you add your domain both with and without `www.` prepended. Cloudflare worker custom domain -If you have trouble setting up a custom subdirectory, -[contact our support team](https://mintlify.com/docs/support) and we'll walk you through -upgrading your hosting with us. + + If your DNS provider is Cloudflare, you should not use proxying for the CNAME record. + -### Edit Worker Script +## Configure routing -Click on `Edit Code` and add the following script into the worker's code. +Choose a setup option based on whether you are hosting other content at your root domain: - - Cloudflare edit code - +* **Docs-only**: Serve documentation at `/docs` with no other content at your domain. +* **Multiple origins**: Serve documentation at `/docs` while hosting your main site at the root domain. - - Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and - `CUSTOM_URL` with your website's base URL. - +### Docs-only setup -```javascript -addEventListener("fetch", (event) => { - event.respondWith(handleRequest(event.request)); -}); +1. Select `Edit Code` and add the following script into the Worker's code. -async function handleRequest(request) { - try { - const urlObject = new URL(request.url); - // If the request is to the docs subdirectory - if (/^\/docs/.test(urlObject.pathname)) { - // Then Proxy to Mintlify - const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; - const CUSTOM_URL = "[YOUR_DOMAIN]"; + + Edit Code button emphasized in the Cloudflare user interface. + - let url = new URL(request.url); - url.hostname = DOCS_URL; + + Replace `[SUBDOMAIN]` with your unique subdomain and `[YOUR_DOMAIN]` with your website's base URL. + - let proxyRequest = new Request(url, request); + ```javascript + addEventListener("fetch", (event) => { + event.respondWith(handleRequest(event.request)); + }); - proxyRequest.headers.set("Host", DOCS_URL); - proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); - proxyRequest.headers.set("X-Forwarded-Proto", "https"); + async function handleRequest(request) { + try { + const urlObject = new URL(request.url); + // If the request is to the docs subdirectory + if (/^\/docs/.test(urlObject.pathname)) { + // Then Proxy to Mintlify + const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; + const CUSTOM_URL = "[YOUR_DOMAIN]"; - return await fetch(proxyRequest); + let url = new URL(request.url); + url.hostname = DOCS_URL; + + let proxyRequest = new Request(url, request); + + proxyRequest.headers.set("Host", DOCS_URL); + proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); + proxyRequest.headers.set("X-Forwarded-Proto", "https"); + + return await fetch(proxyRequest); + } + } catch (error) { + // If no action found, serve the regular request + return await fetch(request); } - } catch (error) { - // if no action found, play the regular request - return await fetch(request); } -} -``` - -Click on `Deploy` and wait for the changes to propagate (it can take up to a few -hours). + ``` +2. Select `Deploy` and wait for the changes to propagate, which can take up to a few hours. + +### Multiple origins setup + +If you use a website builder, like Webflow or Squarespace, or another hosting provider for your main site, configure multiple origins to also host your docs at a `/docs` subdirectory. This setup requires a staging environment because the Worker will proxy all non-docs traffic to your main site. + +1. With your hosting provider, set up a staging domain for your main site like `staging.yoursite.com`. +2. Deploy your main to the staging domain. This ensures that your main site remains accessible while you configure the Worker. +3. Update any absolute URLs in your main site to be relative to avoid conflicts. +4. In Cloudflare, select **Edit Code** and add the following script into the Worker's code. + + Edit Code button emphasized in the Cloudflare user interface. + + + + Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, and `[STAGING_DOMAIN]` with your staging domain URL. + + + ```javascript + addEventListener("fetch", (event) => { + event.respondWith(handleRequest(event.request)); + }); + + async function handleRequest(request) { + try { + const urlObject = new URL(request.url); + + // If the request is to the docs subdirectory + if (/^\/docs/.test(urlObject.pathname)) { + // Proxy to Mintlify + const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; + const CUSTOM_URL = "[YOUR_DOMAIN]"; + + let url = new URL(request.url); + url.hostname = DOCS_URL; + + let proxyRequest = new Request(url, request); + + proxyRequest.headers.set("Host", DOCS_URL); + proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); + proxyRequest.headers.set("X-Forwarded-Proto", "https"); + + return await fetch(proxyRequest); + } + + // Route everything else to main site + const MAIN_SITE_URL = "[STAGING_DOMAIN]"; + if (MAIN_SITE_URL && MAIN_SITE_URL !== "[STAGING_DOMAIN]") { + let mainSiteUrl = new URL(request.url); + mainSiteUrl.hostname = MAIN_SITE_URL; + + return await fetch(mainSiteUrl, { + method: request.method, + headers: request.headers, + body: request.body + }); + } + + } catch (error) { + // If no action found, serve the regular request + return await fetch(request); + } + } + ``` +4. Select `Deploy` and wait for the changes to propagate, which can take up to a few hours. + +Make sure your main site is set up on a staging domain before deploying this worker, or visitors to your main site will see errors. +