Deploy at a subpath with Vercel

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.mintlifysite.com/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 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.
   {
     "rewrites": [
       {
         "source": "/_mintlify/:path*",
         "destination": "https://[subdomain].mintlifysite.com/_mintlify/:path*"
       },
       {
         "source": "/api/request",
         "destination": "https://[subdomain].mintlifysite.com/_mintlify/api/request"
       },
       {
         "source": "/docs",
         "destination": "https://[subdomain].mintlifysite.com/docs"
       },
       {
         "source": "/docs/:match*",
         "destination": "https://[subdomain].mintlifysite.com/docs/:match*"
       },
       {
         "source": "/mintlify-assets/:path+",
         "destination": "https://[subdomain].mintlifysite.com/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 in the Vercel documentation.

​

Host at custom subpath

To use a custom subpath (any path other than /docs):

1. Navigate to the Custom domain setup page in your dashboard.
2. Enable the Host at toggle.
3. Enter your domain.
4. Enter your base path. For example, /docs or /help.
5. Click Add domain.

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.

​

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