You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To host your documentation at a `/docs` subpath using Cloudflare, you will need to create and configure a Cloudflare Worker.
8
+
To host your documentation at a custom subpath such as `yoursite.com/docs` using Cloudflare, you will need to create and configure a Cloudflare Worker.
9
9
10
10
<Info>
11
11
Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare).
12
12
</Info>
13
13
14
+
## Repository structure
15
+
16
+
Your documentation files must be organized within your repository to match your chosen subpath structure. For example, if you want your documentation at `yoursite.com/docs`, you would create a `docs/` directory with all of your documentation files.
17
+
14
18
## Set up a Cloudflare Worker
15
19
16
20
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.
@@ -43,7 +47,7 @@ Ensure that the `HOST` header is correctly forwarded in your Worker configuratio
43
47
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.
44
48
45
49
<Tip>
46
-
Replace `[SUBDOMAIN]` with your unique subdomain and `[YOUR_DOMAIN]` with your website's base URL.
50
+
Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, and `/docs` with your desired subpath if different.
47
51
</Tip>
48
52
49
53
```javascript
@@ -128,7 +132,7 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d
128
132
3. To avoid conflicts, update any absolute URLs in your main site to be relative.
129
133
4. In Cloudflare, select **Edit Code** and add the following script into your Worker's code.
130
134
131
-
<Tip> Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, and `[LANDING_DOMAIN]` with your landing page URL. </Tip>
135
+
<Tip> Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, `[LANDING_DOMAIN]` with your landing page URL, and `/docs` with your desired subpath if different. </Tip>
To host your documentation at a `/docs` subpath using AWS Route 53 and CloudFront, you need to configure your DNS provider to point to your CloudFront distribution.
9
+
To host your documentation at a custom subpath such as `yoursite.com/docs` using AWS Route 53 and CloudFront, you need to configure your DNS provider to point to your CloudFront distribution.
10
+
11
+
## Repository structure
12
+
13
+
Your documentation files must be organized within your repository to match your chosen subpath structure. For example, if you want your documentation at `yoursite.com/docs`, you would create a `docs/` directory with all of your documentation files.
10
14
11
15
## High-level overview
12
16
@@ -80,9 +84,9 @@ By this point, you should have two Origins: one with `[SUBDOMAIN].mintlify.app`
80
84
81
85
## Set behaviors
82
86
83
-
Behaviors in CloudFront enable control over the subpath logic. At a high level, we're looking to create the following logic.
87
+
Behaviors in CloudFront enable control over the subpath logic. At a high level, we're looking to create the following logic:
84
88
85
-
-**If a user lands on /docs**, go to `[SUBDOMAIN].mintlify.dev`.
89
+
-**If a user lands on your custom subpath**, go to `[SUBDOMAIN].mintlify.dev`.
86
90
-**If a user lands on any other page**, go the current landing page.
87
91
88
92
1. Navigate to the "Behaviors" tab of your CloudFront distribution.
@@ -109,9 +113,9 @@ If `.well-known/*` is too generic, it can be narrowed down to 2 behaviors at a m
109
113
-`/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
110
114
</Info>
111
115
112
-
### `/docs`
116
+
### Your custom subpath
113
117
114
-
Create a behavior with a **Path pattern** of `/docs` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`).
118
+
Create a behavior with a **Path pattern** of your chosen subpath, for example `/docs`, with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`).
115
119
116
120
- Set "Cache policy" to **CachingOptimized**.
117
121
- Set "Origin request policy" to **AllViewerExceptHostHeader**.
@@ -121,11 +125,11 @@ Create a behavior with a **Path pattern** of `/docs` with **Origin and origin gr
121
125
122
126
</Frame>
123
127
124
-
### `/docs/*`
128
+
### Your custom subpath with wildcard
125
129
126
-
Create a behavior with a **Path pattern** of `/docs/*` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
130
+
Create a behavior with a **Path pattern** of your chosen subpath followed by `/*`, for example `/docs/*`, and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
127
131
128
-
These settings should exactly match `/docs`. With the exception of the **Path pattern**.
132
+
These settings should exactly match your base subpath behavior. With the exception of the **Path pattern**.
129
133
130
134
- Set "Cache policy" to **CachingOptimized**.
131
135
- Set "Origin request policy" to **AllViewerExceptHostHeader**.
@@ -169,7 +173,7 @@ You can now test if your distribution is set up properly by going to the "Genera
169
173
170
174
</Frame>
171
175
172
-
All pages should be directing to your main landing page, but if you append `/docs` to the URL, you should see it going to your Mintlify documentation instance.
176
+
All pages should be directing to your main landing page, but if you append your chosen subpath, for example `/docs`, to the URL, you should see it going to your Mintlify documentation instance.
173
177
174
178
## Connect with Route53
175
179
@@ -201,6 +205,6 @@ Now, we're going to bring the functionality of the CloudFront distribution into
201
205
You may need to remove the existing A record if one currently exists.
202
206
</Note>
203
207
204
-
Your documentation is now live at `/docs` for your primary domain.
208
+
Your documentation is now live at your chosen subpath for your primary domain.
The `vercel.json` file is Vercel's configuration file that allows you to customize how your project is built and deployed. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
10
+
The `vercel.json` file configures how your project is built and deployed. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
9
11
10
12
We use the `rewrites` configuration to proxy requests from your main domain to your documentation.
11
13
12
-
Rewrites allow you to map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel will internally fetch content from `your-subdomain.mintlify.dev/docs` but the user will still see `yoursite.com/docs` in their browser. This is different from redirects, which would send users to a different URL entirely.
14
+
Rewrites map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel will internally fetch content from `your-subdomain.mintlify.dev/docs` but the user will still see `yoursite.com/docs` in their browser. This is different from redirects, which would send users to a different URL entirely.
15
+
16
+
You can customize the subpath to any value you prefer, such as `/docs`, `/help`, or `/guides`. Additionally, you can use deeply nested subpaths like `/product/docs`.
17
+
18
+
## Repository structure
19
+
20
+
Your documentation files must be organized within your repository to match your chosen subpath structure. For example, if you want your documentation at `yoursite.com/docs`, you would create a `docs/` directory with all of your documentation files.
13
21
14
22
## Configuration
15
23
16
-
To host your documentation at a custom `/docs`subpath using Vercel, add the following configuration to your `vercel.json` file:
24
+
To host your documentation at a custom subpath using Vercel, add the following configuration to your `vercel.json` file. This example uses `/docs`, but you can replace it with any subpath:
17
25
18
26
```json
19
27
{
@@ -32,11 +40,16 @@ To host your documentation at a custom `/docs` subpath using Vercel, add the fol
32
40
33
41
-**`source`**: The path pattern on your domain that triggers the rewrite.
34
42
-**`destination`**: Where the request should be proxied to.
35
-
-**`:match*`**: A wildcard that captures any path segments after `/docs/`.
36
-
43
+
-**`:match*`**: A wildcard that captures any path segments after your subpath.
37
44
38
45
For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation.
39
46
47
+
### Generate rewrites
48
+
49
+
Enter your subdomain and custom subdirectory to generate the rewrites for your `vercel.json` file.
50
+
51
+
<VercelJsonGenerator />
52
+
40
53
## Using external proxies with Vercel
41
54
42
55
If you're using an external proxy (like Cloudflare or AWS CloudFront) in front of your Vercel deployment, you must configure it properly to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
0 commit comments