Skip to content

Add DNS conflict resolution to Cloudflare subpath docs #791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jun 7, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 38 additions & 35 deletions advanced/subpath/cloudflare.mdx
Original file line number Diff line number Diff line change
@@ -1,51 +1,28 @@
---
title: "Cloudflare"
description: "Host documentation at a /docs subpath using Cloudflare Workers"

Check warning on line 3 in advanced/subpath/cloudflare.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

advanced/subpath/cloudflare.mdx#L3

Did you really mean 'subpath'?
---

## Create Cloudflare Worker
To host your documentation at a `/docs` subpath using Cloudflare, you will need to create and configure a 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.
<Info>
Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare).
</Info>

<Frame>
<img alt="Create a Cloudflare worker" src="/images/cloudflare/worker.png" />
</Frame>
## Set up a Cloudflare Worker

Create a Cloudflare Worker by following the [Cloudflare Workers getting started guide](https://developers.cloudflare.com/workers/get-started/dashboard/), if you have not already.

<Warning>
Keep in mind: If your DNS provider is Cloudflare you should not use proxying for the CNAME record
If your DNS provider is Cloudflare, do not use proxying for the CNAME record.

Check warning on line 17 in advanced/subpath/cloudflare.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

advanced/subpath/cloudflare.mdx#L17

Did you really mean 'proxying'?
</Warning>

### 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.

<Frame>
<img
alt="Cloudflare worker custom domain"
src="/images/cloudflare/custom-domain.png"
/>
</Frame>

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.
### Configure routing

### Edit Worker Script

Click on `Edit Code` and add the following script into the worker's code.

<Frame>
<img alt="Cloudflare edit code" src="/images/cloudflare/edit-code.png" />
</Frame>
In your Cloudflare dashboard, select **Edit Code** and add the following script into your Worker's code. See the [Cloudflare documentation](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) for more information on editing a Worker.

<Tip>
Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and
`CUSTOM_URL` with your website's base URL.
Replace `[SUBDOMAIN]` with your unique subdomain and `[YOUR_DOMAIN]` with your website's base URL.
</Tip>

```javascript
Expand Down Expand Up @@ -80,5 +57,31 @@
}
```

Click on `Deploy` and wait for the changes to propagate (it can take up to a few
Select `Deploy` and wait for the changes to propagate (it can take up to a few
hours).

### Test your Worker

After your code deploys, test your Worker to ensure it routes to your Mintlify docs.

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

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.

<Tip>
We recommend you add your domain both with and without `www.` prepended.

Check warning on line 77 in advanced/subpath/cloudflare.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

advanced/subpath/cloudflare.mdx#L77

Did you really mean 'prepended'?
</Tip>

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

If your domain already points to another service, you must remove the existing DNS record. Your Cloudflare Worker must be configured to control all traffic for your domain.

1. Delete the existing DNS record for your domain. See [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) in the Cloudflare documentation for more information.
2. Return to your Worker and add your custom domain.