mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
f66b301e00
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
111 lines
5.0 KiB
Plaintext
111 lines
5.0 KiB
Plaintext
---
|
|
title: "Deploy at a subpath with Vercel"
|
|
sidebarTitle: "Vercel"
|
|
description: "Serve your Mintlify site at a subpath on your main domain using Vercel rewrites, with a step-by-step vercel.json configuration walkthrough."
|
|
keywords: ["vercel.json", "Vercel deployment", "rewrites configuration", "subpath routing", "external proxy", "CloudFront", "domain verification", "SSL certificates"]
|
|
boost: 3
|
|
---
|
|
|
|
import { VercelJsonGenerator } from "/snippets/vercel-json-generator.mdx";
|
|
import SubpathSetupSteps from "/snippets/subpath-setup-steps.mdx";
|
|
|
|
Configure your `vercel.json` file to proxy requests from your main domain to your documentation at a subpath.
|
|
|
|
## The vercel.json file
|
|
|
|
The `vercel.json` file configures how your project builds and deploys. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
|
|
|
|
Mintlify uses the `rewrites` configuration in your `vercel.json` file to proxy requests from your main domain to your documentation.
|
|
|
|
Rewrites map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel internally fetches content from `your-subdomain.mintlify.site/docs`, but the user still sees `yoursite.com/docs` in their browser. This is different from redirects, which send users to another URL entirely.
|
|
|
|
## Configuration
|
|
|
|
### Host at `/docs` subpath
|
|
|
|
1. Navigate to [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) in your dashboard.
|
|
2. Enable the **Host at** toggle.
|
|
3. Enter your domain.
|
|
4. Enter `docs` as your base path.
|
|
5. Click **Add domain**.
|
|
6. Add the following rewrites to your `vercel.json` file. Replace `[subdomain]` with your subdomain, which appears at the end of your dashboard URL. For example, `app.mintlify.com/your-organization/your-subdomain` has a domain identifier of `your-subdomain`.
|
|
|
|
```json
|
|
{
|
|
"rewrites": [
|
|
{
|
|
"source": "/_mintlify/:path*",
|
|
"destination": "https://[subdomain].mintlify.site/_mintlify/:path*"
|
|
},
|
|
{
|
|
"source": "/api/request",
|
|
"destination": "https://[subdomain].mintlify.site/_mintlify/api/request"
|
|
},
|
|
{
|
|
"source": "/docs",
|
|
"destination": "https://[subdomain].mintlify.site/docs"
|
|
},
|
|
{
|
|
"source": "/docs/:match*",
|
|
"destination": "https://[subdomain].mintlify.site/docs/:match*"
|
|
},
|
|
{
|
|
"source": "/mintlify-assets/:path+",
|
|
"destination": "https://[subdomain].mintlify.site/mintlify-assets/:path+"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The `rewrites` configuration maps the `/docs` subpath on your domain to the `/docs` subpath on your documentation.
|
|
|
|
- **`source`**: The path pattern on your domain that triggers the rewrite.
|
|
- **`destination`**: Where the request should be proxied to.
|
|
- **`:match*`**: A wildcard that captures any path segments after your subpath.
|
|
|
|
The `/_mintlify` and `/mintlify-assets` rewrites are required for the API playground and static assets.
|
|
|
|
For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation.
|
|
|
|
### Host at custom subpath
|
|
|
|
To use a custom subpath (any path other than `/docs`):
|
|
|
|
<SubpathSetupSteps />
|
|
|
|
Then use the generator below to create your rewrites configuration and add the rewrites to your `vercel.json` file.
|
|
|
|
Mintlify rebuilds your documentation to serve at your base path, so your documentation files do not need to be in a directory that matches your subpath.
|
|
|
|
<VercelJsonGenerator />
|
|
|
|
## External proxies in front of Vercel
|
|
|
|
If you have an external proxy like Cloudflare or AWS CloudFront in front of your Vercel deployment, configure it properly. This avoids conflicts with Vercel's domain verification and SSL certificate provisioning.
|
|
|
|
Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
|
|
|
|
See the [supported providers](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite) in the Vercel documentation.
|
|
|
|
### Required path allowlist
|
|
|
|
Your external proxy must allow traffic to these specific paths without blocking, redirecting, or heavily caching:
|
|
|
|
- `/.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.
|
|
|
|
Your proxy should pass these paths directly to your Vercel deployment without modification.
|
|
|
|
### Header forwarding requirements
|
|
|
|
Ensure that your proxy correctly forwards the `Host` header. Without proper header forwarding, verification requests fail.
|
|
|
|
### Test your proxy setup
|
|
|
|
To verify your proxy is correctly configured:
|
|
|
|
1. Test that `https://[yourdomain].com/.well-known/vercel/` returns a response.
|
|
2. Ensure SSL certificates are provisioning correctly in your Vercel dashboard.
|
|
3. Check that domain verification completes successfully.
|