Custom Domains

Overview

Every HolyDocs project gets a default subdomain at your-slug.holydocs.com. You can also configure a custom domain like docs.yourcompany.com to serve your documentation under your own brand.

Want to serve docs at a path on your existing site (e.g., yourcompany.com/docs) instead of a subdomain? See Subfolder Hosting.

Setting Up a Custom Domain

text
docs.yourcompany.com

Custom Domain via API

You can also configure domains programmatically:

Get Domain Status

bash
curl "https://api.holydocs.com/api/v1/domains/PROJECT_ID" \  -H "Authorization: Bearer YOUR_API_KEY"

Or from the CLI:

bash
holydocs api get /domains/PROJECT_ID

Response:

json
{  "data": {    "subdomain": "my-project.holydocs.com",    "customDomain": "docs.yourcompany.com",    "cnameTarget": "proxy.holydocs.com",    "analysis": {      "hostnameReady": true,      "cnameMatchesTarget": true,      "sslStatus": "active"    }  }}

Set Custom Domain

bash
curl -X PUT "https://api.holydocs.com/api/v1/domains/PROJECT_ID" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "customDomain": "docs.yourcompany.com" }'

bash
holydocs api put /domains/PROJECT_ID \  --json '{"customDomain":"docs.yourcompany.com"}'

Verify Custom Domain

bash
holydocs api post /domains/PROJECT_ID/verify

Remove Custom Domain

bash
curl -X DELETE "https://api.holydocs.com/api/v1/domains/PROJECT_ID" \  -H "Authorization: Bearer YOUR_API_KEY"

Domain Limits by Plan

The default *.holydocs.com subdomain is always available and does not count toward your custom domain limit.

Apex Domains

If you want to use an apex domain (e.g., yourcompany.com without a subdomain), your DNS provider must support CNAME flattening or ALIAS records:

• Cloudflare — Supports CNAME flattening automatically
• AWS Route 53 — Use an ALIAS record pointing to proxy.holydocs.com
• Other providers — Check if CNAME flattening is supported; otherwise use a subdomain

Troubleshooting

Domain not verifying

• Confirm the CNAME record is pointing to proxy.holydocs.com (not your old host)
• DNS propagation can take up to 48 hours, though it usually completes in minutes
• Check for conflicting A records on the same hostname

SSL errors

• SSL certificates are provisioned automatically after DNS verification
• Certificate provisioning typically takes 1-2 minutes after verification
• If SSL is not working after 10 minutes, try removing and re-adding the domain

Domain already in use

Each custom domain can only be assigned to one HolyDocs project. If you see an "already in use" error, check if the domain is assigned to another project in your organization.