Custom Domain HTTPS on Read the Docs: Unresolved Wildcard Certificate Support

Answer

Read the Docs does not currently support wildcard certificates for custom domains; each subdomain must have its own Let's Encrypt certificate issued by the platform.

Likely explanation

The automated certificate workflow uses HTTP‑01 or DNS‑01 challenges that validate a single fully‑qualified domain name. Because the service ties a certificate to a specific project and expects the exact Host header, a wildcard (*.example.com) cannot be renewed or served through the same flow.

Confirmed facts

• Read the Docs provisions a free Let's Encrypt cert for each custom domain you add in the project settings (CNAME or A/ALIAS for apex).
• There is no option to upload or use a wildcard certificate; the UI shows only per‑domain management.
• Apex domains still require a cert for the exact host (e.g., example.com) even if you use CNAME flattening at your DNS provider.

Steps needed for many subdomains

1. Add each subdomain as a separate custom domain in the Read the Docs project settings.
2. Ensure each subdomain points via CNAME to readthedocs.org (or use an A/ALIAS record for the apex).
3. Let's Encrypt will issue an individual certificate for each entry; renewal is handled automatically.

When a workaround changes the recommendation

If you can place a reverse proxy or CDN (e.g., Cloudflare, NGINX) in front of Read the Docs, you may terminate TLS with your own wildcard certificate and proxy traffic to readthedocs.org while preserving the original Host header. This avoids per‑subdomain certs on Read the Docs but requires you to manage the proxy and ensure the Host header is passed unchanged.

Missing diagnostic detail: Do you have the ability to deploy a reverse proxy or CDN in front of your Read the Docs site? Your answer determines whether the proxy‑based wildcard approach is viable.