Custom Subpath Setup Overview
Deploy your documentation at a custom subpath like yoursite.com/docs using reverse proxy configuration.
What is a Custom Subpath Deployment?
A custom subpath deployment allows you to host your documentation at a specific path on your domain, such as yoursite.com/docs, yoursite.com/help, yoursite.com/documentation, or any custom path you choose, rather than on a separate subdomain like docs.yoursite.com.
This approach integrates your documentation seamlessly into your main website while maintaining a unified domain structure.
You have complete flexibility in choosing your subpath. Throughout this guide, we use /docs as an example, but you can replace it with any path like /help, /guide, /api-docs, /support, or /documentation.
How It Works
Custom subpath deployments use a reverse proxy to route traffic:
- User visits
yoursite.com/[SUBPATH] - Reverse proxy intercepts the request
- Proxy forwards the request to your documentation hosting
- Documentation responds with the content
- Proxy returns the response to the user
- Browser displays content at
yoursite.com/[SUBPATH]
The reverse proxy acts as an intermediary, allowing you to serve documentation from a different hosting provider while maintaining your primary domain.
Benefits
Unified Domain
Keep everything under one domain for better brand consistency and user experience.
SEO Benefits
Consolidate domain authority and improve search engine rankings.
Simplified SSL
Manage SSL certificates in one place rather than across multiple subdomains.
User Trust
Users stay on your main domain, building trust and reducing confusion.
Use Cases
Marketing Sites with Docs Integrate documentation directly into your product marketing site without requiring users to navigate to a separate subdomain.
Developer Portals Create unified developer experiences where API docs, guides, and product pages coexist under the same domain.
Multi-Product Documentation
Use different subpaths for different products: yoursite.com/product-a/docs and yoursite.com/product-b/docs.
Enterprise Requirements Meet corporate policies that require all public-facing content on the primary domain.
Architecture Overview
The reverse proxy:
- Routes
/[SUBPATH]/*traffic to your documentation hosting - Routes all other traffic to your main website
- Handles SSL termination
- Forwards necessary headers for domain verification
Deployment Options Comparison
| Provider | Setup Complexity | Performance | Cost | Best For |
|---|---|---|---|---|
| Vercel | Low | Excellent | Free tier available | Next.js sites, fast setup |
| Cloudflare Workers | Medium | Excellent | Free tier generous | Global distribution, flexibility |
| AWS CloudFront | High | Excellent | Pay as you go | Enterprise, AWS ecosystem |
Prerequisites
Before setting up a custom subpath deployment, ensure you have:
Documentation Hosted
Your documentation must be deployed and accessible at [SUBDOMAIN].documentationai.io.
Domain Access
Administrative access to your domain's DNS settings and hosting configuration.
SSL Certificate
A valid SSL certificate for your domain (most providers offer free SSL).
Reverse Proxy Platform
An account with Vercel, Cloudflare, AWS, or another reverse proxy service.
Important Considerations
Domain Verification Required: When using a custom subpath, you must configure your reverse proxy to allow traffic to /.well-known/* paths. These paths are required for SSL certificate verification and domain ownership validation.
Required Path Allowlist
Your reverse proxy configuration must allow these paths to pass through without modification:
/.well-known/acme-challenge/*- Required for Let's Encrypt SSL certificate verification/.well-known/vercel/*- Required for domain verification (if using Vercel)
Header Forwarding
Ensure your reverse proxy forwards the following headers:
Host: [SUBDOMAIN].documentationai.io
X-Forwarded-Host: yoursite.com
X-Forwarded-Proto: https
Choosing a Provider
Select the guide that matches your infrastructure:
Vercel
Simple JSON configuration for Vercel deployments.
Cloudflare Workers
Flexible worker scripts for advanced routing.
AWS Route 53 & CloudFront
Enterprise-grade AWS infrastructure setup.
Next Steps
Choose your deployment platform and follow the corresponding guide:
- Review the platform-specific guide
- Configure your reverse proxy
- Update DNS settings
- Test your deployment
- Monitor for proper routing
Start with a staging environment to test your configuration before applying it to production.
Last updated 2 days ago