# Hosting Docs at yoursite.com/docs

Serve your docs under a path on your main domain, like `yoursite.com/docs`, instead of a separate subdomain. This is how most modern product docs are set up, and it has a real SEO benefit: your docs and your main site build authority as one domain instead of splitting it.

These docs work exactly this way. You are reading them at `clayo.com/docs`.

## How it works

Two things make a subpath work, and your AI tool can do both in one session:

1. **Clayo learns your base URL.** Every link, canonical tag, sitemap entry, and published-article URL switches to `https://yoursite.com/docs/...`.
2. **Your site forwards the path.** Whatever already serves `yoursite.com` forwards `/docs` traffic to your Clayo origin. No DNS changes, no certificates: your domain keeps pointing at your own infrastructure.

## Step 1: Set your base URL

Ask your AI tool (Claude Code, Cursor, or Codex, with the [Clayo MCP server installed](https://clayo.com/docs/articles/installing-the-mcp-server)):

> Serve our Clayo docs at https://yoursite.com/docs

The agent calls the `set_docs_base_url` tool, and Clayo's reply includes the exact rewrite rule for step 2, so the agent can usually finish the whole setup on its own.

:::callout{type="info"}
The base URL must be `https`, on a domain you own, with exactly one path segment: `/docs` or `/help` works, `/help/docs` doesn't. You need to be a project owner or admin.
:::

## Step 2: Forward the path from your site

Add a rewrite to whatever serves your domain. The one rule that matters: **forward the full path, including the `/docs` prefix**. Don't strip it; Clayo expects the prefix and answers a stripped request with a redirect, which turns into a loop through your proxy.

::::tabs

:::tab{label="Vercel / Next.js"}
In `vercel.json`:

```json
{
  "rewrites": [
    { "source": "/docs", "destination": "https://yourproject.clayo.site/docs" },
    { "source": "/docs/:path*", "destination": "https://yourproject.clayo.site/docs/:path*" }
  ]
}
```

Or in `next.config.ts`:

```ts
async rewrites() {
  return [
    { source: "/docs", destination: "https://yourproject.clayo.site/docs" },
    { source: "/docs/:path*", destination: "https://yourproject.clayo.site/docs/:path*" },
  ]
}
```
:::

:::tab{label="Cloudflare"}
Create a Worker on the route `yoursite.com/docs*`:

```js
export default {
  async fetch(request) {
    const url = new URL(request.url)
    return fetch(
      `https://yourproject.clayo.site${url.pathname}${url.search}`,
      request
    )
  },
}
```

The path passes through unchanged, which is exactly what Clayo expects.
:::

:::tab{label="nginx"}
```nginx
location /docs {
  proxy_pass https://yourproject.clayo.site;
  proxy_set_header Host yourproject.clayo.site;
  proxy_ssl_server_name on;
}
```

`proxy_pass` without a URI part forwards the original path, prefix included.
:::

::::

Replace `yourproject` with your Clayo subdomain in each snippet.

## Verify

Open `https://yoursite.com/docs`. You should land on your first article, and every link in the sidebar should stay under `/docs`. From the command line:

```bash
curl -sSI https://yoursite.com/docs
```

Expect a `200`, or a redirect that stays under `/docs`.

## What changes, and what keeps working

- Your sitemap, `llms.txt`, canonical URLs, and the links Clayo returns when you publish all point at your subpath.
- `yourproject.clayo.site` keeps working: it permanently redirects (308) to your subpath, so links you've already shared stay valid and search engines transfer ranking to the new URLs.
- Search, AI answers, and the support widget all follow along. Nothing else to configure.

## Subpath or custom domain?

Clayo supports both. Quick guide:

| | Subpath (`yoursite.com/docs`) | Custom domain (`docs.yoursite.com`) |
| --- | --- | --- |
| SEO | Shares your main domain's authority | Builds authority separately |
| Setup | A rewrite in your own infrastructure | DNS records, Clayo handles SSL |
| Best when | Your main site can proxy a path | You want zero changes to your site's config |

If both are configured, the subpath wins as the canonical address.

## Undoing it

Ask your AI tool to remove the base URL (it calls `remove_docs_base_url`), and your docs immediately fall back to your previous address. Then delete the rewrite from your site's config; until you do, it will keep forwarding traffic to your docs origin.