diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index eb5c05a2dd..cb3f3c0d77 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -118,6 +118,38 @@ If your domain is still pending validation after adding the verification `TXT` r Only retry validation after you confirm that your DNS records are correct. Repeated retries with incorrect records do not speed up validation. +## Limitations and lifecycle + +Custom domains have a few lifecycle constraints that are not obvious during setup. Review these before you migrate a production site. + +### The default `.mintlify.site` subdomain is permanent + +The `.mintlify.site` URL is assigned when the deployment is first created and cannot be changed later. Renaming your project or organization only updates the display name in the dashboard; it does not rename the URL. + +If you push to a deployment whose display name no longer matches the original subdomain, requests to preview URLs can return a `Disallowed origin host` error until the site rebuilds against the original subdomain. + +To change the `.mintlify.site` subdomain, you must: + +1. Back up any content and settings you want to keep. Deleting a deployment removes everything associated with it. +2. Delete the deployment from the [Danger zone](https://app.mintlify.com/settings/organization/danger-zone). See [Delete a deployment](/deploy/deployments#delete-a-deployment). +3. Create a new deployment and enter the desired name during setup. + +### The default subdomain stays live after adding a custom domain + +Once a custom domain is verified, your documentation is served from both the custom domain and the original `.mintlify.site` URL. The default subdomain cannot currently be disabled, and there is no automatic redirect from it to your custom domain. + +To consolidate on the custom domain in search results, set a [canonical URL](#set-a-canonical-url) so search engines index the custom domain as the primary version. + +### One primary custom domain per project + +Mintlify serves each documentation project from a single primary custom domain. Pointing multiple hostnames (for example, `developers.example.com` and `docs.example.com`) at the same project through the dashboard is not supported. + +If you need multiple hostnames or multiple projects under one domain, choose the option that fits your setup: + +- **Multiple hostnames for one project**: Configure a self-managed reverse proxy (for example, Cloudflare Workers) in front of Mintlify so each hostname rewrites to the primary custom domain. See [Reverse proxy](/deploy/reverse-proxy). +- **Multiple projects under one domain as subpaths**: Use a [multi-repository deployment](/deploy/multi-repo) to combine several repositories into one site with dedicated URL paths. Multi-repository deployments are available on Enterprise plans. +- **Docs under a subpath of an existing site**: See [Host docs at a /docs subpath](/deploy/docs-subpath). + ## Set a canonical URL After configuring your DNS, set a canonical URL to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content. diff --git a/deploy/deployments.mdx b/deploy/deployments.mdx index 2859ff253a..874d562090 100644 --- a/deploy/deployments.mdx +++ b/deploy/deployments.mdx @@ -30,6 +30,10 @@ If you have the GitHub App installed, but changes are still not deploying, manua You can permanently delete a deployment from the [Danger zone](https://app.mintlify.com/settings/organization/danger-zone) in your dashboard settings. This action is irreversible and removes all deployment data, including any associated preview deployments. + + Deleting and recreating a deployment is currently the only way to change the `.mintlify.site` URL assigned at creation. See [Limitations and lifecycle](/customize/custom-domain#limitations-and-lifecycle) for details. + + Go to the [Danger zone](https://app.mintlify.com/settings/organization/danger-zone) in the settings page of your dashboard. diff --git a/deploy/multi-repo.mdx b/deploy/multi-repo.mdx index 300201f8e7..9c9cb97158 100644 --- a/deploy/multi-repo.mdx +++ b/deploy/multi-repo.mdx @@ -5,7 +5,7 @@ keywords: ["multi-repo", "multiple repositories", "git sources", "URL path"] --- - Multi-repository deployments are available on [Enterprise plans](https://mintlify.com/pricing?ref=multi-repo). + Multi-repository deployments are available on [Enterprise plans](https://mintlify.com/pricing?ref=multi-repo). For other multi-domain and multi-project routing options, see [Limitations and lifecycle](/customize/custom-domain#limitations-and-lifecycle). Use a multi-repository deployment when one site needs content from more than one Git repository. When you configure multiple repositories as sources for the same Mintlify project, content from each repository has its own URL path. diff --git a/deploy/reverse-proxy.mdx b/deploy/reverse-proxy.mdx index 4a8e1249c7..bf1ea0f77f 100644 --- a/deploy/reverse-proxy.mdx +++ b/deploy/reverse-proxy.mdx @@ -8,6 +8,10 @@ To serve your documentation through a custom reverse proxy, you must configure r When you implement a reverse proxy, monitor for potential issues with domain verification, SSL certificate provisioning, authentication flows, performance, and analytics tracking. + + Mintlify serves each project from a single primary custom domain. To route additional hostnames to the same documentation, or to combine multiple projects under one domain, see [Limitations and lifecycle](/customize/custom-domain#limitations-and-lifecycle). + + ## Choose your deployment approach Mintlify supports two reverse proxy configurations depending on your subpath requirements.