Custom Subpath Setup

Vercel Subpath Setup

Host documentation at a custom subpath using Vercel rewrites configuration.

Overview

Deploy your documentation at a custom subpath such as yoursite.com/docs, yoursite.com/help, or any path you choose using Vercel's powerful rewrite functionality. This guide walks you through configuring your Vercel project to proxy requests from your chosen subpath to your documentation hosting.

Use any subpath: /docs, /help, /guide, etc. Replace /docs in examples with your chosen path.

How Vercel Rewrites Work

Vercel rewrites allow you to map incoming request paths to different destinations without changing the URL in the browser. When a user visits yoursite.com/docs, Vercel internally proxies the request to your documentation hosting and returns the content seamlessly.

Repository Structure

Your main site repository structure remains unchanged. The subpath configuration is handled entirely through vercel.json:

your-project/
├── vercel.json          # Rewrite configuration
├── public/              # Main site assets
├── src/                 # Main site source
└── package.json

Configuration Steps

Create vercel.json

In the root of your Vercel project, create or update the vercel.json file with the rewrite configuration.

Configure Rewrites

Add the complete rewrite rules to proxy documentation requests.

Deploy to Vercel

Commit your changes and deploy to Vercel.

Test the Configuration

Verify that your documentation is accessible at the custom subpath.

Complete Vercel Configuration

Create a vercel.json file in your project root with the following configuration:

Replace [SUBDOMAIN] with your subdomain and [SUBPATH] with your chosen path.

{
  "rewrites": [
    {
      "source": "/_dai/api/:path*",
      "destination": "http://[SUBDOMAIN].documentatioai.com/_dai/api/:path*"
    },
    {
      "source": "/dai-assets/:path+",
      "destination": "http://[SUBDOMAIN].documentatioai.com/dai-assets/:path+"
    },
    {
      "source": "/[SUBPATH]",
      "destination": "http://[SUBDOMAIN].documentatioai.com/[SUBPATH]"
    },
    {
      "source": "/[SUBPATH]/:path*",
      "destination": "http://[SUBDOMAIN].documentatioai.com/[SUBPATH]/:path*"
    },
    {
      "source": "/[SUBPATH]/llms.txt",
      "destination": "http://[SUBDOMAIN].documentatioai.com/llms.txt"
    },
    {
      "source": "/[SUBPATH]/sitemap.xml",
      "destination": "http://[SUBDOMAIN].documentatioai.com/sitemap.xml"
    },
    {
      "source": "/[SUBPATH]/robots.txt",
      "destination": "http://[SUBDOMAIN].documentatioai.com/robots.txt"
    }
  ]
}

Understanding the Rewrite Rules

Let's break down each rewrite rule and its purpose:

1. API Routes

{
  "source": "/_dai/api/:path*",
  "destination": "http://[SUBDOMAIN].documentatioai.com/_dai/api/:path*"
}

Proxies internal API requests required for documentation features like search, analytics, and interactive playground.

2. Static Assets

{
  "source": "/dai-assets/:path+",
  "destination": "http://[SUBDOMAIN].documentatioai.com/dai-assets/:path+"
}

Forwards requests for documentation assets (CSS, JavaScript, images) to the documentation hosting.

3. Documentation Root

{
  "source": "/[SUBPATH]",
  "destination": "http://[SUBDOMAIN].documentatioai.com/[SUBPATH]"
}

Handles requests to the documentation root path (e.g., yoursite.com/[SUBPATH]).

4. Documentation Pages

{
  "source": "/[SUBPATH]/:path*",
  "destination": "http://[SUBDOMAIN].documentatioai.com/[SUBPATH]/:path*"
}

Proxies all documentation page requests with the :path* wildcard matching any nested paths.

5. SEO and Discovery Files

{
  "source": "/[SUBPATH]/llms.txt",
  "destination": "http://[SUBDOMAIN].documentatioai.com/llms.txt"
},
{
  "source": "/[SUBPATH]/sitemap.xml",
  "destination": "http://[SUBDOMAIN].documentatioai.com/sitemap.xml"
},
{
  "source": "/[SUBPATH]/robots.txt",
  "destination": "http://[SUBDOMAIN].documentatioai.com/robots.txt"
}

Maps SEO-critical files (LLM discovery, sitemap, robots.txt) from the documentation host to your subpath.

Domain Verification

Vercel requires domain verification for custom domains. The rewrite configuration automatically allows verification paths to pass through:

/.well-known/acme-challenge/* - Let's Encrypt SSL certificate verification
/.well-known/vercel/* - Vercel domain ownership verification

Testing Your Configuration

After deploying your configuration:

Test Root Path

Visit yoursite.com/[SUBPATH] and verify the documentation loads correctly.

Test Nested Pages

Navigate to a nested documentation page like yoursite.com/[SUBPATH]/getting-started/introduction.

Check Assets

Open browser DevTools and verify all assets (images, CSS, JavaScript) load without errors.

Verify SEO Files

Test access to yoursite.com/[SUBPATH]/sitemap.xml and yoursite.com/[SUBPATH]/robots.txt.

Test Search

Use the documentation search functionality to ensure the API routes work correctly.

Advanced Configuration

Custom Headers

Add custom headers to your rewrite rules if needed:

{
  "rewrites": [
    {
      "source": "/[SUBPATH]/:path*",
      "destination": "http://[SUBDOMAIN].documentatioai.com/[SUBPATH]/:path*",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  ]
}

Multiple Subpaths

Host different documentation instances on different subpaths:

{
  "rewrites": [
    {
      "source": "/[SUBPATH-1]/:path*",
      "destination": "http://[SUBDOMAIN-1].documentatioai.com/[SUBPATH-1]/:path*"
    },
    {
      "source": "/[SUBPATH-2]/:path*",
      "destination": "http://[SUBDOMAIN-2].documentatioai.com/[SUBPATH-2]/:path*"
    }
  ]
}

Redirects for Old Paths

Redirect old documentation URLs to the new subpath:

{
  "redirects": [
    {
      "source": "/documentation/:path*",
      "destination": "/[SUBPATH]/:path*",
      "permanent": true
    }
  ],
  "rewrites": [
    // ... your existing rewrites
  ]
}

Ensure your documentation includes proper Cache-Control headers
Static assets should have long cache durations
API responses should have short or no cache durations

Edge Network

Vercel's edge network serves content from the location closest to your users, reducing latency and improving performance globally.

Next Steps

After successfully configuring your Vercel subpath deployment:

Monitor your Vercel dashboard for traffic and errors
Set up custom domain SSL if not already configured
Configure analytics to track documentation usage
Test your documentation thoroughly across different pages
Update any internal links to use the new subpath

✅ Your documentation is now live!

Was this page helpful?

Built with Documentation.AI

Last updated today