> ## Documentation Index
> [HTML page](https://blode.md/docs/guides/proxy-vercel)
> [Documentation index](https://blode.md/docs/llms.txt)
> Use the index to discover all available pages before exploring further.

# Proxy /docs through Vercel

Host Edda docs at yourdomain.com/docs by adding rewrites for /docs and /_docs to your Next.js next.config.js on an existing Vercel marketing site.

If your marketing site already lives on Vercel, you can host docs at
`yourdomain.com/docs` without a custom domain on Edda. One rewrite, two
minutes.

## next.config.js

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      {
        source: "/docs",
        destination: "https://acme.blode.md",
      },
      {
        source: "/docs/:path*",
        destination: "https://acme.blode.md/:path*",
      },
      {
        source: "/_docs/:path*",
        destination: "https://acme.blode.md/_docs/:path*",
      },
    ];
  },
};

export default nextConfig;
```

Replace `acme` with your project slug. The first two rewrites forward every
request under `/docs` to your Edda site, so search and navigation keep
working.

The third one is easy to miss and the page renders unstyled without it. Shared
CSS, JavaScript and fonts are served from `/_docs/*` at the root of your domain
, not under `/docs`: because they are the same files for every page, so they
need their own rewrite.

## Strip the prefix in Edda

Edda serves content at the root by default. If you serve at `/docs`, set
the path prefix on your default subdomain in **Dashboard → Project →
Domains** (the path prefix field on the default subdomain row), or pass
`pathPrefix: "/docs"` when creating the domain via the API.

## Declare your public URL

A rewrite is invisible to us: the request we receive from Vercel looks
identical to someone visiting `acme.blode.md` directly, so we cannot tell that
your domain sits in front. Tell us where the site is published:

```json docs.json
{
  "seo": {
    "siteUrl": "https://yourdomain.com/docs"
  }
}
```

Include the path prefix if you use one. Canonical tags, `og:url`, JSON-LD, the
sitemap, `llms.txt` and the `.md` alternates are all built from this value.

Skip it and every page canonicalises to `acme.blode.md`, which tells search
engines the Edda subdomain is the real home of your content and leaves your
own domain out of the index.

## Verifying the proxy

After deploying, hit `https://yourdomain.com/docs`: you should see the
homepage of your Edda site rendered under your domain. View the network
tab to confirm requests are 200 OK and being proxied.

## Why proxy?

- One canonical domain for SEO.
- No DNS work for users: pages just appear under your existing site.
- Switch backends later by changing the rewrite target.

## Troubleshooting

- **Page renders as unstyled HTML**: the `/_docs/:path*` rewrite is missing.
  Every stylesheet and script 404s without it.
- **404 on assets**: double-check the path prefix matches what you set in the
  domain config.
- **Redirect loops**: make sure your Edda project doesn't have a
  conflicting custom domain configured for the same hostname.
- **Stale content**: Vercel caches rewrites at the edge; redeploy after
  changes to `next.config.js`.
- **Agents get HTML when they ask for Markdown**: Edda answers
  `Accept: text/markdown` on every page URL, but Vercel caches the proxied
  HTML under the page URL without `Accept` in the cache key, so once a page is
  cached the negotiated request returns that HTML. Coding agents that send the
  header (Claude Code, Cursor) then read your HTML shell. Either point them at
  the explicit `.md` URL, or add a `proxy.ts` that rewrites `/docs/*` requests
  with `text/markdown` in `Accept` to `/docs/*.md` before the cache is
  consulted. The `.md` twin is its own URL and therefore its own cache entry.