VitePress Custom Domain on Free Hosting (Cloudflare Pages)

Tested on: Cloudflare Pages free tier, VitePress 1.6.3 Domain: docs.myproduct.com → Cloudflare Pages project

VitePress config for apex/subdomain

export default defineConfig({
  base: '/',
  lang: 'en-US',
  title: 'My Docs',
  sitemap: {
    hostname: 'https://docs.myproduct.com'
  }
})

No base prefix when hosting at subdomain root.

Cloudflare Pages setup

1. Connect Git repo
2. Build: npm run docs:build
3. Output: docs/.vitepress/dist
4. Env: NODE_VERSION=20

Custom domain → Add docs.myproduct.com

DNS (auto if domain on Cloudflare):

CNAME docs → my-docs.pages.dev

TLS: Full (strict) — automatic cert.

WWW redirect

Cloudflare Rules → Redirect www.docs... → apex (or vice versa).

_redirects for old paths

docs/public/_redirects:

/old-guide/*  /guide/:splat  301

Cloudflare Pages reads _redirects from dist.

apex on same repo (marketing + docs)

Use separate projects OR path-based:

base: '/docs/' if served at myproduct.com/docs/.

Subdomain is simpler — base: '/'.

Errors

SSL handshake failed

DNS still propagating to old host. Orange-cloud DNS only after Pages domain verified.

Canonical URLs point to pages.dev

Set sitemap.hostname and head meta:

head: [['link', { rel: 'canonical', href: 'https://docs.myproduct.com/' }]]

Verify

curl -I https://docs.myproduct.com/
# HTTP/2 200, cf-ray present

curl -I https://docs.myproduct.com/guide/start/
# 200

SSL Labs test A rating.

Result

Custom domain live in 15 minutes. TTFB ~40ms globally.