Skip to main content

​
vercel.json file

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. We use the rewrites configuration 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.dev/docs, but the user still sees yoursite.com/docs in their browser. This is different from redirects, which send users to another URL entirely. 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.

​
Configuration

​
Host from /docs

  1. Navigate to Custom domain setup in your dashboard.
  2. Click the Host at /docs toggle to the on position.
Screenshot of the Custom domain setup page. The Host at `/docs` toggle is on and highlighted by an orange rectangle.
  1. Enter your domain.
  2. Select Add domain.
  3. Add the following rewrites to your vercel.json file. Replace [subdomain] with your subdomain:
{
  "rewrites": [
    {
      "source": "/docs",
      "destination": "https://[subdomain].mintlify.dev/docs"
    },
    {
      "source": "/docs/:match*",
      "destination": "https://[subdomain].mintlify.dev/docs/:match*"
    }
  ]
}
  • 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.
For more information, see Configuring projects with vercel.json: Rewrites in the Vercel documentation.

​
Host from custom path

To use a custom subpath (any path other than /docs), you must organize your documentation files within your repository to match your subpath structure. For example, if your documentation is hosted at yoursite.com/help, your documentation files must be in a help/ directory. Use the generator below to create your rewrites configuration. Add the rewrites to your vercel.json file.

​
Using external proxies with Vercel

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. 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
These paths should pass through 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 will fail.

​
Testing 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.
⌘I