> ## Documentation Index > Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt > Use this file to discover all available pages before exploring further. # Subfolder Hosting Host your HolyDocs documentation under a subfolder of your main website like yoursite.com/docs. ## Overview By default, HolyDocs documentation is served from a subdomain like `docs.yourcompany.com`. Subfolder hosting lets you serve your documentation from a path on your main domain instead, such as `yourcompany.com/docs`. This is useful when you want your documentation to share the same domain as your marketing site or application for SEO benefits and a unified brand experience. ## How It Works Subfolder hosting uses a reverse proxy on your main web server to forward requests from a specific path (e.g., `/docs`) to your HolyDocs project. HolyDocs then strips the `basePath` from incoming requests and serves the correct page. The request flow: ``` Reader visits yourcompany.com/docs/quickstart -> Your web server matches /docs/* and proxies to HolyDocs -> HolyDocs strips /docs from the path -> HolyDocs renders /quickstart and returns it -> Reader sees the page at yourcompany.com/docs/quickstart ``` Subfolder hosting is available on Starter plans and above. You must also have a custom domain configured or use the default subdomain with a proxy. ## Setting Up basePath ### Via docs.json Add the `hosting.basePath` field to your `docs.json`: ```json { "name": "My Docs", "hosting": { "basePath": "/docs" } } ``` The `basePath` must start with a `/` and should not include a trailing slash. ### Via the Dashboard 1. Go to **Settings → Domain** in your project dashboard 2. Under **Subfolder Hosting**, enter your base path (e.g., `/docs`) and click **Save** 3. Follow the proxy setup guide on this page to configure your web server 4. Use the **Validate Setup** button in the dashboard to confirm the proxy is reaching HolyDocs After setting the basePath, all internal links in your documentation are automatically prefixed. For example, a link to `/quickstart` will be rendered as `/docs/quickstart` in the HTML output. You do not need to update your MDX files. Deploy your project after saving the base path so pre-rendered pages and canonical URLs pick up the change. HolyDocs serves subfolder-hosted projects via live rendering (not pre-rendered HTML) so that canonical and `og:url` tags reflect your public URL rather than the renderer's hostname. ## Configuring Your Proxy Your main web server needs to forward requests from the basePath to your HolyDocs project. Below are configurations for the most common platforms. **Set `X-Forwarded-Host` and `X-Forwarded-Proto` on every proxied request.** HolyDocs uses these headers to build canonical URLs, Open Graph tags, sitemap entries, and the `robots.txt` Sitemap reference. Without them, search engines will see canonical URLs pointing at `your-project.holydocs.com/docs/...` instead of `yourcompany.com/docs/...`, which fragments SEO the exact way subfolder hosting is meant to avoid. The Nginx, Caddy, Apache, and Cloudflare Worker examples below set these headers. Vercel rewrites and Netlify redirects forward the original `Host` implicitly but cannot set custom forwarded headers — if you need SEO-correct canonical URLs on those platforms, use a Next.js middleware or Netlify Edge Function instead of a plain rewrite. **Nginx** ```nginx server { listen 443 ssl; server_name yourcompany.com; # Your main site location / { # ... your existing configuration } # Proxy documentation to HolyDocs location /docs/ { proxy_pass https://your-project.holydocs.com/; proxy_set_header Host your-project.holydocs.com; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Base-Path /docs; proxy_ssl_server_name on; } # Handle /docs without trailing slash location = /docs { return 301 /docs/; } } ``` The trailing slash on `proxy_pass` is important. `proxy_pass https://your-project.holydocs.com/` (with trailing slash) strips the `/docs/` prefix from the forwarded request. Without it, the full path including `/docs/` is forwarded. **Vercel** Add a `rewrites` rule to your `vercel.json`: ```json { "rewrites": [ { "source": "/docs/:path*", "destination": "https://your-project.holydocs.com/:path*" } ] } ``` If your Vercel project uses Next.js, add the rewrite to `next.config.js` instead: ```javascript module.exports = { async rewrites() { return [ { source: '/docs/:path*', destination: 'https://your-project.holydocs.com/:path*', }, ]; }, }; ``` **Cloudflare Workers** If your main site is on Cloudflare, create a Worker to proxy documentation requests: ```javascript export default { async fetch(request) { const url = new URL(request.url); // Proxy /docs/* to HolyDocs if (url.pathname === '/docs' || url.pathname.startsWith('/docs/')) { const docsPath = url.pathname.replace(/^\/docs/, '') || '/'; const docsUrl = new URL(docsPath, 'https://your-project.holydocs.com'); docsUrl.search = url.search; const headers = new Headers(request.headers); headers.set('X-Forwarded-Host', url.host); headers.set('X-Forwarded-Proto', url.protocol.replace(':', '')); return fetch(docsUrl.toString(), { method: request.method, headers, body: request.body, redirect: 'manual', }); } // Pass through to origin for everything else return fetch(request); }, }; ``` Attach this Worker via a Route to `yourcompany.com/docs/*` so it only runs on documentation requests. **Netlify** Add a rewrite rule to your `netlify.toml`: ```toml [[redirects]] from = "/docs/*" to = "https://your-project.holydocs.com/:splat" status = 200 force = true ``` Or add to your `_redirects` file: ``` /docs/* https://your-project.holydocs.com/:splat 200 ``` **Apache** ```apache ServerName yourcompany.com # Enable proxy + header modules (a2enmod proxy proxy_http headers) ProxyRequests Off SSLProxyEngine On # Proxy documentation to HolyDocs ProxyPass /docs/ https://your-project.holydocs.com/ ProxyPassReverse /docs/ https://your-project.holydocs.com/ # Tell HolyDocs what the public URL is so canonical/og tags are correct RequestHeader set X-Forwarded-Host "%{HTTP_HOST}s" RequestHeader set X-Forwarded-Proto "https" # Handle /docs without trailing slash RedirectMatch 301 ^/docs$ /docs/ # Your main site configuration # ... ``` **Caddy** ``` yourcompany.com { # Proxy /docs to HolyDocs handle_path /docs/* { reverse_proxy https://your-project.holydocs.com { header_up Host your-project.holydocs.com header_up X-Forwarded-Host {host} header_up X-Forwarded-Proto {scheme} } } # Redirect /docs to /docs/ @docspath path /docs redir @docspath /docs/ # Your main site handle { # ... your existing configuration } } ``` ## How HolyDocs Strips basePath When a request reaches HolyDocs with a `basePath` configured, the renderer strips the base path from the incoming request URL before routing to a page. For example, with `basePath: "/docs"`: | Incoming Request | Stripped Path | Page Served | |---|---|---| | `/docs/` | `/` | `introduction.mdx` (root page) | | `/docs/quickstart` | `/quickstart` | `quickstart.mdx` | | `/docs/api/authentication` | `/api/authentication` | `api/authentication.mdx` | | `/docs/sitemap.xml` | `/sitemap.xml` | Generated sitemap | | `/docs/llms.txt` | `/llms.txt` | Generated llms.txt | | `/docs/_assets/logo.svg` | `/_assets/logo.svg` | Logo asset | All generated assets (sitemap, robots.txt, llms.txt, OG images) are also served under the basePath. ## Testing the Setup **Configure basePath** Set `hosting.basePath` in your `docs.json` or dashboard and deploy: ```bash holydocs deploy ``` **Configure your proxy** Add the appropriate proxy configuration to your web server using the examples above. **Test the root path** Visit `yourcompany.com/docs/` in your browser. You should see your documentation home page. **Test deep links** Navigate to a specific page like `yourcompany.com/docs/quickstart`. Verify the content renders correctly and the browser URL stays on your domain. **Test internal navigation** Click links within the documentation. All internal links should stay under `yourcompany.com/docs/` without redirecting to the HolyDocs subdomain. **Test search** Use the search bar. Results should link to pages under your basePath, not the HolyDocs subdomain. **Test assets** Verify that images, fonts, and CSS load correctly. Open your browser's network tab and check for any failed requests or mixed-content warnings. ## Limitations and Considerations **Custom domain required for production** For production use, you should have a custom domain configured in HolyDocs. While you can proxy to the default subdomain (`your-project.holydocs.com`), using a custom domain ensures proper SSL handling and avoids potential CORS issues. **basePath cannot be nested more than one level** The basePath must be a single path segment like `/docs` or `/help`. Multi-level paths like `/company/docs` are not supported. If you need a deeper path, configure the proxy to rewrite the path to a single segment before forwarding. **Preview deployments use the subdomain** Preview deployments (from pull requests) are served from the HolyDocs subdomain, not your basePath. The basePath only applies to production deployments served through your proxy. **Caching behavior** Your proxy server may cache responses from HolyDocs. Make sure your proxy respects the `Cache-Control` headers returned by HolyDocs. Avoid adding additional caching layers that could serve stale content after a deployment. **SSE for AI assistant** The AI assistant chat widget uses Server-Sent Events (SSE) for streaming responses. Ensure your proxy supports SSE pass-through and does not buffer the response. For Nginx, add `proxy_buffering off;` to the location block. ## SEO Implications Subfolder hosting has positive SEO implications compared to subdomain hosting: **Domain authority sharing** Documentation pages at `yourcompany.com/docs` inherit the domain authority of your main site. Subdomains are treated as separate entities by search engines, so content at `docs.yourcompany.com` does not benefit from your main domain's authority. **Unified link equity** Backlinks to your documentation pages contribute to the overall link equity of your main domain. With subdomain hosting, link equity is split between the main domain and the docs subdomain. **Consistent canonical URLs** HolyDocs generates canonical URLs using your basePath, so search engines index the correct URL under your main domain. **Shared cookie scope** If you use cookie-based analytics on your main site, documentation pages under the same domain share the same cookie scope, giving you unified analytics across your entire web presence. While subfolder hosting has SEO advantages, subdomain hosting (`docs.yourcompany.com`) is simpler to set up and does not require any proxy configuration. If SEO is not a primary concern, subdomain hosting is the recommended approach for most projects. ## Troubleshooting **Pages returning 404** Verify that your proxy rule forwards the request path correctly. The most common issue is the proxy including the base path in the forwarded URL, resulting in a double path like `/docs/docs/quickstart`. Ensure the `proxy_pass` URL has a trailing slash (Nginx) or the rewrite strips the prefix. **Assets not loading (CSS, images, fonts)** Ensure your proxy forwards all paths under the base path, including `/_assets/` and static file paths. Some proxy configurations only forward HTML page requests. The proxy rule should match `/docs/*` (all paths), not just specific extensions. **Links pointing to the HolyDocs subdomain** Make sure the `hosting.basePath` is set in your `docs.json` or dashboard before deploying. Without this configuration, HolyDocs generates links without the base path prefix, causing them to point to the root domain or subdomain instead of the subfolder. **Search and AI assistant not working** The AI assistant uses Server-Sent Events (SSE) for streaming. Ensure your proxy does not buffer responses. For Nginx, add `proxy_buffering off;` and `proxy_read_timeout 300s;` to the location block. For Cloudflare Workers, SSE pass-through works by default.