diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index 4a0ddb58f..5fce31e80 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -35,7 +35,7 @@ You can host your documentation at the root of a domain, a subdomain, or a subpa If your domain traffic routes to Mintlify, the dashboard displays the DNS records to add at your domain provider. -If you proxy only your subpath to Mintlify, the dashboard displays reverse proxy setup guides instead. Follow the guide for your provider and see [Host docs at a subpath](/deploy/docs-subpath) for more information. +If you proxy only your subpath to Mintlify, follow the reverse proxy guide for your provider instead of adding the `CNAME` record. See [Host docs at a subpath](/deploy/docs-subpath) for more information. If your proxy runs on Cloudflare, the verification `TXT` records shown in your dashboard stay unverified in this setup. This is expected. See [_cf-custom-hostname TXT record stuck unverified](/help-center/cf-custom-hostname-txt-record-stuck-unverified). You can also add a domain from the terminal with [`mint add-domain `](/cli/commands#mint-add-domain). The command registers the domain on your project and prints the DNS records to configure. @@ -136,7 +136,7 @@ If you need zero downtime during migration, set the `CNAME` record's proxy statu 1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/project/custom-domain) page in your dashboard. 2. Find your pending custom domain. -3. Click **Retry validation**. +3. Click **Re-verify domain**. Only retry validation after you confirm that your DNS records are correct. Repeated retries with incorrect records do not speed up validation. diff --git a/deploy/docs-subpath.mdx b/deploy/docs-subpath.mdx index fa577482d..5f53497ac 100644 --- a/deploy/docs-subpath.mdx +++ b/deploy/docs-subpath.mdx @@ -22,6 +22,10 @@ If another site runs on your domain, configure your hosting provider to proxy yo - [Vercel](/deploy/vercel): Use rewrites to deploy your documentation at your subpath. - [Custom reverse proxy](/deploy/reverse-proxy): For other hosting platforms, set up a reverse proxy to deploy your documentation at your subpath. + + When your own proxy serves your subpath, do not add the `CNAME` record shown on the [Custom domain setup](https://app.mintlify.com/settings/project/custom-domain) page. It routes all traffic for the domain to Mintlify and bypasses your proxy. If your proxy runs on Cloudflare, the verification `TXT` records also stay unverified. This is expected and does not affect your documentation. See [_cf-custom-hostname TXT record stuck unverified](/help-center/cf-custom-hostname-txt-record-stuck-unverified). + + ### Additional configuration for strict security policies If you proxy all traffic on your custom domain, you may need to configure your proxy or firewall rules to add the correct [headers](/deploy/csp-configuration). This ensures that your documentation displays properly. diff --git a/docs.json b/docs.json index c55a46980..4c521aba6 100644 --- a/docs.json +++ b/docs.json @@ -496,7 +496,9 @@ "help-center/migrate-from-confluence", "help-center/migrate-docs-from-a-zip-export", "help-center/agent-opens-pull-requests-against-deploy-branch", - "help-center/publish-button-disabled-invalid-mdx" + "help-center/publish-button-disabled-invalid-mdx", + "help-center/host-multiple-docs-sites-on-one-domain", + "help-center/cf-custom-hostname-txt-record-stuck-unverified" ] } ] diff --git a/es.json b/es.json index 6e6f14981..b5157c0dd 100644 --- a/es.json +++ b/es.json @@ -474,7 +474,9 @@ "es/help-center/migrate-from-confluence", "es/help-center/migrate-docs-from-a-zip-export", "es/help-center/agent-opens-pull-requests-against-deploy-branch", - "es/help-center/publish-button-disabled-invalid-mdx" + "es/help-center/publish-button-disabled-invalid-mdx", + "es/help-center/host-multiple-docs-sites-on-one-domain", + "es/help-center/cf-custom-hostname-txt-record-stuck-unverified" ] } ] diff --git a/es/customize/custom-domain.mdx b/es/customize/custom-domain.mdx index 08409f3ba..d8f304e58 100644 --- a/es/customize/custom-domain.mdx +++ b/es/customize/custom-domain.mdx @@ -39,7 +39,7 @@ Puedes alojar tu documentación en la raíz de un dominio, en un subdominio o en Si el tráfico de tu dominio se enruta a Mintlify, el dashboard muestra los registros DNS que debes añadir en tu proveedor de dominio. -Si solo redireccionas tu subruta a Mintlify, el dashboard muestra guías de configuración de proxy inverso en su lugar. Sigue la guía correspondiente a tu proveedor y consulta [Alojar la documentación en una subruta](/es/deploy/docs-subpath) para más información. +Si solo redireccionas tu subruta a Mintlify, sigue la guía de proxy inverso correspondiente a tu proveedor en lugar de añadir el registro `CNAME`. Consulta [Alojar la documentación en una subruta](/es/deploy/docs-subpath) para más información. Si tu proxy se ejecuta en Cloudflare, los registros `TXT` de verificación que se muestran en tu dashboard permanecen sin verificar en esta configuración. Esto es lo esperado. Consulta [Registro TXT _cf-custom-hostname atascado sin verificar](/es/help-center/cf-custom-hostname-txt-record-stuck-unverified). También puedes añadir un dominio desde la terminal con [`mint add-domain `](/es/cli/commands#mint-add-domain). El comando registra el dominio en tu proyecto e imprime los registros DNS que debes configurar. @@ -162,7 +162,7 @@ Los registros `TXT` suelen validarse en cinco minutos. Si tu dominio sigue pendi 1. Ve a la página de [configuración de dominio personalizado](https://app.mintlify.com/settings/project/custom-domain) en tu dashboard. 2. Busca tu dominio personalizado pendiente. -3. Haz clic en **Retry validation**. +3. Haz clic en **Re-verify domain**. Reintenta la validación solo después de confirmar que tus registros DNS son correctos. Los reintentos repetidos con registros incorrectos no aceleran la validación. diff --git a/es/deploy/docs-subpath.mdx b/es/deploy/docs-subpath.mdx index 8638edd61..363892cd1 100644 --- a/es/deploy/docs-subpath.mdx +++ b/es/deploy/docs-subpath.mdx @@ -26,6 +26,10 @@ Si otro sitio se ejecuta en tu dominio, configura tu proveedor de hosting para r - [Vercel](/es/deploy/vercel): Usa reescrituras para desplegar tu documentación en tu subruta. - [Proxy inverso personalizado](/es/deploy/reverse-proxy): Para otras plataformas de hosting, configura un proxy inverso para desplegar tu documentación en tu subruta. + + Cuando tu propio proxy sirve tu subruta, no añadas el registro `CNAME` que se muestra en la página de [configuración de dominio personalizado](https://app.mintlify.com/settings/project/custom-domain). Este registro enruta todo el tráfico del dominio a Mintlify y omite tu proxy. Si tu proxy se ejecuta en Cloudflare, los registros `TXT` de verificación también permanecen sin verificar. Esto es lo esperado y no afecta a tu documentación. Consulta [Registro TXT _cf-custom-hostname atascado sin verificar](/es/help-center/cf-custom-hostname-txt-record-stuck-unverified). + +
### Configuración adicional para políticas de seguridad estrictas
diff --git a/es/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx b/es/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx new file mode 100644 index 000000000..bbb1e82ab --- /dev/null +++ b/es/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx @@ -0,0 +1,31 @@ +--- +title: "Registro TXT _cf-custom-hostname atascado sin verificar" +description: "Por qué los registros TXT de verificación permanecen sin verificar cuando el proxy de tu subruta se ejecuta en Cloudflare, y por qué puedes ignorarlo." +keywords: ["_cf-custom-hostname", "_acme-challenge", "registro TXT sin verificar", "verificación de dominio atascada", "pending validation", "subruta con proxy", "Cloudflare Worker", "proxy inverso"] +--- + +Si alojas tu documentación en una subruta detrás de un proxy inverso que se ejecuta en Cloudflare, como un Cloudflare Worker que reenvía `example.com/docs` a `.mintlify.site`, la página de [configuración de dominio personalizado](https://app.mintlify.com/settings/project/custom-domain) sigue mostrando los registros `TXT` de verificación `_cf-custom-hostname` y `_acme-challenge`. En esta configuración, esos registros nunca aparecen como verificados, incluso si los añades en tu proveedor de DNS y haces clic en **Re-verify domain**. + +Esto es específico de los proxies que se ejecutan en Cloudflare. Si el proxy de tu subruta se ejecuta en otra plataforma, como Vercel o un proxy inverso nginx personalizado, los registros `TXT` se verifican mediante una consulta DNS estándar y no dependen de hacia dónde se enruta tu tráfico. Si permanecen sin verificar en ese caso, confirma que los añadiste exactamente como se muestran en el proveedor de DNS autoritativo de tu dominio. + +
+ ## Por qué los registros nunca se verifican +
+ +Tu dominio ya pasa por el proxy de Cloudflare, la misma red que usa Mintlify para verificar hostnames personalizados. En esta configuración, Cloudflare no puede completar la verificación de los registros `TXT` solo mediante una consulta DNS. Requiere que el tráfico del hostname se enrute primero a través de su red hasta Mintlify, el mismo requisito descrito en [Dominios detrás del proxy de Cloudflare](/es/customize/custom-domain#cloudflare-proxied-domains). + +Cuando tu propio proxy basado en Cloudflare sirve la subruta, el tráfico de tu dominio termina en tu proxy y nunca llega al edge de Mintlify, por lo que tu configuración nunca puede cumplir este requisito. Tu proxy termina TLS con su propio certificado y reenvía las solicitudes a `.mintlify.site`, que ya tiene un certificado válido, por lo que los registros permanecen sin verificar indefinidamente. + +
+ ## Qué hacer +
+ +Nada. El estado sin verificar no afecta a tu documentación. Para confirmar que tu configuración funciona, visita tu subruta, como `example.com/docs`, y comprueba que tu documentación carga mediante HTTPS. + +No añadas el registro `CNAME` que se muestra en el dashboard. Enruta todo el tráfico del dominio a Mintlify y omite tu proxy. Aun así necesitas habilitar el interruptor **Host at** y añadir tu dominio con su ruta base en el dashboard para que Mintlify construya tu sitio en la subruta correcta. Consulta [Alojar la documentación en una subruta](/es/deploy/docs-subpath) y la [guía de Cloudflare Workers](/es/deploy/cloudflare). + +
+ ## Cuándo sí importa la verificación +
+ +Si el tráfico de tu dominio se enruta a Mintlify a través del `CNAME`, los registros `TXT` deben verificarse antes de que se complete el aprovisionamiento de TLS. Si tu dominio pasa por el proxy de Cloudflare (nube naranja), la verificación solo se completa después de que actualices el `CNAME`. Consulta [Dominios detrás del proxy de Cloudflare](/es/customize/custom-domain#cloudflare-proxied-domains). diff --git a/es/help-center/host-multiple-docs-sites-on-one-domain.mdx b/es/help-center/host-multiple-docs-sites-on-one-domain.mdx new file mode 100644 index 000000000..4821c9538 --- /dev/null +++ b/es/help-center/host-multiple-docs-sites-on-one-domain.mdx @@ -0,0 +1,39 @@ +--- +title: "¿Puedo alojar varios sitios de docs en el mismo dominio?" +description: "Un dominio personalizado se conecta a un proyecto de Mintlify. Combina productos en un sitio con navegación por rutas o usa subdominios." +keywords: ["varios sitios de documentación", "mismo dominio", "documentación multiproducto", "dominio personalizado", "un proyecto por dominio", "subdominio por producto", "consolidar sitios de documentación"] +--- + +Un dominio personalizado se conecta exactamente a un proyecto de Mintlify. No puedes apuntar `example.com/product-a` a un proyecto y `example.com/product-b` a otro. Si intentas añadir un dominio que otro proyecto ya tiene, el dashboard devuelve un error `Domain is already in use by another deployment in your organization` o `Domain is already claimed by another organization`. Consulta [Corregir el error "Domain already claimed by another organization"](/es/help-center/domain-already-claimed-by-another-organization). + +Para documentar varios productos, elige uno de estos patrones. + +
+ ## Un solo sitio con navegación por rutas +
+ +Combina todos los productos en un solo proyecto y sepáralos con la navegación. Cada producto obtiene su propia ruta de URL en el dominio compartido, como `docs.example.com/product-a` y `docs.example.com/product-b`. + +- Usa [productos](/es/organize/navigation#products), [pestañas](/es/organize/navigation#tabs) o [menús desplegables](/es/organize/navigation#dropdowns) en tu `docs.json` para dar a cada producto una división de navegación dedicada. +- Si la documentación de cada producto vive en su propio repositorio de Git, usa un [proyecto multi-repositorio](/es/deploy/multi-repo) para combinar los repositorios en un solo sitio con una ruta de URL por repositorio. Los proyectos multi-repositorio están disponibles en los planes Enterprise. + +Este patrón mantiene todos los productos buscables desde un solo lugar y requiere un único dominio personalizado. + +
+ ## Sitios separados en subdominios separados +
+ +Mantén cada producto como su propio proyecto y asigna a cada proyecto su propio subdominio, como `docs-product-a.example.com` y `docs-product-b.example.com`. Añade cada subdominio como el [dominio personalizado](/es/customize/custom-domain) de su proyecto. + +Usa este patrón cuando los productos necesiten sitios totalmente independientes, por ejemplo con equipos, temas o procesos de lanzamiento separados. + +
+ ## Consolida sitios existentes +
+ +Si mueves sitios separados a un solo proyecto: + +1. Mueve el contenido al proyecto combinado y organízalo con la navegación. +2. Añade [redirecciones](/es/create/redirects) en `docs.json` para cualquier ruta de página que haya cambiado. Las redirecciones solo se aplican dentro del proyecto que las define. +3. Elimina el dominio personalizado de cada proyecto retirado para que el dominio quede liberado. Consulta [Elimina un dominio personalizado](/es/customize/custom-domain#remove-a-custom-domain). +4. Redirige el tráfico de los subdominios retirados en tu proveedor de DNS o capa de hosting. Mintlify no puede redirigir un dominio que ya no está conectado a un proyecto. diff --git a/fr.json b/fr.json index e7d9d8718..003591ad2 100644 --- a/fr.json +++ b/fr.json @@ -474,7 +474,9 @@ "fr/help-center/migrate-from-confluence", "fr/help-center/migrate-docs-from-a-zip-export", "fr/help-center/agent-opens-pull-requests-against-deploy-branch", - "fr/help-center/publish-button-disabled-invalid-mdx" + "fr/help-center/publish-button-disabled-invalid-mdx", + "fr/help-center/host-multiple-docs-sites-on-one-domain", + "fr/help-center/cf-custom-hostname-txt-record-stuck-unverified" ] } ] diff --git a/fr/customize/custom-domain.mdx b/fr/customize/custom-domain.mdx index 70704deb5..45902e51a 100644 --- a/fr/customize/custom-domain.mdx +++ b/fr/customize/custom-domain.mdx @@ -39,7 +39,7 @@ Vous pouvez héberger votre documentation à la racine d’un domaine, sur un so Si le trafic de votre domaine est acheminé vers Mintlify, le Dashboard affiche les enregistrements DNS à ajouter chez votre fournisseur de domaine. -Si vous ne transmettez que votre sous-chemin à Mintlify via un proxy, le Dashboard affiche à la place des guides de configuration de proxy inverse. Suivez le guide correspondant à votre fournisseur et consultez [Héberger la documentation sur un sous-chemin](/fr/deploy/docs-subpath) pour plus d’informations. +Si vous ne transmettez que votre sous-chemin à Mintlify via un proxy, suivez le guide de proxy inverse correspondant à votre fournisseur au lieu d’ajouter l’enregistrement `CNAME`. Consultez [Héberger la documentation sur un sous-chemin](/fr/deploy/docs-subpath) pour plus d’informations. Si votre proxy s’exécute sur Cloudflare, les enregistrements `TXT` de vérification affichés dans votre Dashboard restent non vérifiés dans cette configuration. C’est un comportement attendu. Consultez [Enregistrement TXT _cf-custom-hostname non vérifié](/fr/help-center/cf-custom-hostname-txt-record-stuck-unverified). Vous pouvez également ajouter un domaine depuis le terminal avec [`mint add-domain `](/fr/cli/commands#mint-add-domain). La commande enregistre le domaine sur votre projet et affiche les enregistrements DNS à configurer. @@ -162,7 +162,7 @@ Les enregistrements `TXT` sont généralement validés en cinq minutes. Si votre 1. Accédez à la page [Configuration du domaine personnalisé](https://app.mintlify.com/settings/project/custom-domain) dans votre Dashboard. 2. Repérez votre domaine personnalisé en attente. -3. Cliquez sur **Retry validation**. +3. Cliquez sur **Re-verify domain**. Ne relancez la validation qu’après avoir vérifié que vos enregistrements DNS sont corrects. Des relances répétées avec des enregistrements incorrects n’accélèrent pas la validation. diff --git a/fr/deploy/docs-subpath.mdx b/fr/deploy/docs-subpath.mdx index 2b80c75a0..89d73eca8 100644 --- a/fr/deploy/docs-subpath.mdx +++ b/fr/deploy/docs-subpath.mdx @@ -26,6 +26,10 @@ Si un autre site fonctionne sur votre domaine, configurez votre fournisseur d’ - [Vercel](/fr/deploy/vercel) : utilisez des réécritures pour déployer votre documentation à votre sous-chemin. - [Proxy inverse personnalisé](/fr/deploy/reverse-proxy) : pour d’autres plateformes d’hébergement, configurez un proxy inverse pour déployer votre documentation à votre sous-chemin. + + Lorsque votre propre proxy sert votre sous-chemin, n’ajoutez pas l’enregistrement `CNAME` affiché sur la page [Configuration du domaine personnalisé](https://app.mintlify.com/settings/project/custom-domain). Il achemine tout le trafic du domaine vers Mintlify et contourne votre proxy. Si votre proxy s’exécute sur Cloudflare, les enregistrements `TXT` de vérification restent également non vérifiés. C’est un comportement attendu et cela n’affecte pas votre documentation. Consultez [Enregistrement TXT _cf-custom-hostname non vérifié](/fr/help-center/cf-custom-hostname-txt-record-stuck-unverified). + +
### Configuration supplémentaire pour des stratégies de sécurité strictes
diff --git a/fr/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx b/fr/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx new file mode 100644 index 000000000..a8f8c2099 --- /dev/null +++ b/fr/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx @@ -0,0 +1,31 @@ +--- +title: "Enregistrement TXT _cf-custom-hostname non vérifié" +description: "Pourquoi les enregistrements TXT de vérification restent non vérifiés quand le proxy de votre sous-chemin s’exécute sur Cloudflare, et pourquoi c’est sans danger." +keywords: ["_cf-custom-hostname", "_acme-challenge", "TXT record unverified", "domain verification stuck", "pending validation", "sous-chemin proxifié", "Cloudflare Worker", "proxy inverse"] +--- + +Si vous hébergez votre documentation sur un sous-chemin derrière un proxy inverse qui s’exécute sur Cloudflare, par exemple un Cloudflare Worker qui transmet `example.com/docs` vers `.mintlify.site`, la page [Configuration du domaine personnalisé](https://app.mintlify.com/settings/project/custom-domain) affiche quand même les enregistrements `TXT` de vérification `_cf-custom-hostname` et `_acme-challenge`. Dans cette configuration, ces enregistrements n’apparaissent jamais comme vérifiés, même si vous les ajoutez chez votre fournisseur DNS et cliquez sur **Re-verify domain**. + +Ceci est spécifique aux proxys qui s’exécutent sur Cloudflare. Si le proxy de votre sous-chemin s’exécute sur une autre plateforme, comme Vercel ou un proxy inverse nginx personnalisé, les enregistrements `TXT` se vérifient via une requête DNS standard et ne dépendent pas de l’endroit où votre trafic est acheminé. S’ils restent non vérifiés dans ce cas, vérifiez que vous les avez ajoutés exactement comme indiqué chez le fournisseur DNS faisant autorité pour votre domaine. + +
+ ## Pourquoi les enregistrements ne sont jamais vérifiés +
+ +Votre domaine est déjà proxifié via Cloudflare, le même réseau que Mintlify utilise pour vérifier les hostnames personnalisés. Dans cette configuration, Cloudflare ne peut pas terminer la vérification des enregistrements `TXT` par une simple requête DNS. Il exige que le trafic du hostname soit d’abord acheminé via son réseau vers Mintlify, la même exigence décrite dans [Domaines derrière un proxy Cloudflare](/fr/customize/custom-domain#cloudflare-proxied-domains). + +Lorsque votre propre proxy basé sur Cloudflare sert le sous-chemin, le trafic de votre domaine se termine au niveau de votre proxy et n’atteint jamais l’edge de Mintlify, si bien que votre configuration ne peut jamais satisfaire cette exigence. Votre proxy termine le TLS avec son propre certificat et transmet les requêtes vers `.mintlify.site`, qui dispose déjà d’un certificat valide, donc les enregistrements restent non vérifiés indéfiniment. + +
+ ## Que faire +
+ +Rien. Le statut non vérifié n’affecte pas votre documentation. Pour confirmer que votre configuration fonctionne, visitez votre sous-chemin, comme `example.com/docs`, et vérifiez que votre documentation se charge en HTTPS. + +N’ajoutez pas l’enregistrement `CNAME` affiché dans le Dashboard. Il achemine tout le trafic du domaine vers Mintlify et contourne votre proxy. Vous devez tout de même activer le bouton **Host at** et ajouter votre domaine avec son chemin de base dans le Dashboard pour que Mintlify construise votre site au bon sous-chemin. Consultez [Héberger la documentation sur un sous-chemin](/fr/deploy/docs-subpath) et le [guide Cloudflare Workers](/fr/deploy/cloudflare). + +
+ ## Quand la vérification compte +
+ +Si le trafic de votre domaine est acheminé vers Mintlify via le `CNAME`, les enregistrements `TXT` doivent être vérifiés pour que le provisionnement TLS aboutisse. Si votre domaine est derrière un proxy Cloudflare (nuage orange), la vérification n’aboutit qu’après la mise à jour du `CNAME`. Consultez [Domaines derrière un proxy Cloudflare](/fr/customize/custom-domain#cloudflare-proxied-domains). diff --git a/fr/help-center/host-multiple-docs-sites-on-one-domain.mdx b/fr/help-center/host-multiple-docs-sites-on-one-domain.mdx new file mode 100644 index 000000000..7c19903ae --- /dev/null +++ b/fr/help-center/host-multiple-docs-sites-on-one-domain.mdx @@ -0,0 +1,39 @@ +--- +title: "Héberger plusieurs docs sur le même domaine ?" +description: "Un domaine personnalisé se connecte à un seul projet Mintlify. Combinez vos produits en un site avec navigation par chemins ou des sous-domaines." +keywords: ["plusieurs sites de documentation", "même domaine", "documentation multi-produits", "domaine personnalisé", "un projet par domaine", "sous-domaine par produit", "consolider des sites de docs"] +--- + +Un domaine personnalisé se connecte à exactement un projet Mintlify. Vous ne pouvez pas faire pointer `example.com/product-a` vers un projet et `example.com/product-b` vers un autre. Si vous essayez d’ajouter un domaine qu’un autre projet détient déjà, le Dashboard renvoie une erreur `Domain is already in use by another deployment in your organization` ou `Domain is already claimed by another organization`. Consultez [Corriger l’erreur "Domain already claimed by another organization"](/fr/help-center/domain-already-claimed-by-another-organization). + +Pour documenter plusieurs produits, choisissez l’un de ces modèles. + +
+ ## Un seul site avec une navigation par chemins +
+ +Combinez tous les produits en un seul projet et séparez-les avec la navigation. Chaque produit dispose de son propre chemin d’URL sur le domaine partagé, comme `docs.example.com/product-a` et `docs.example.com/product-b`. + +- Utilisez des [products](/fr/organize/navigation#products), des [tabs](/fr/organize/navigation#tabs) ou des [dropdowns](/fr/organize/navigation#dropdowns) dans votre `docs.json` pour donner à chaque produit une division de navigation dédiée. +- Si la documentation de chaque produit se trouve dans son propre dépôt Git, utilisez un [projet multi-référentiels](/fr/deploy/multi-repo) pour combiner les dépôts en un seul site avec un chemin d’URL par dépôt. Les projets multi-référentiels sont disponibles avec les formules Enterprise. + +Ce modèle garde tous les produits consultables depuis un seul endroit et ne nécessite qu’un seul domaine personnalisé. + +
+ ## Des sites distincts sur des sous-domaines distincts +
+ +Conservez chaque produit comme un projet à part entière et donnez à chaque projet son propre sous-domaine, comme `docs-product-a.example.com` et `docs-product-b.example.com`. Ajoutez chaque sous-domaine comme [domaine personnalisé](/fr/customize/custom-domain) de son projet. + +Utilisez ce modèle lorsque les produits ont besoin de sites totalement indépendants, par exemple avec des équipes, des thèmes ou des processus de publication distincts. + +
+ ## Consolider des sites existants +
+ +Si vous regroupez des sites distincts en un seul projet : + +1. Déplacez le contenu dans le projet combiné et organisez-le avec la navigation. +2. Ajoutez des [redirections](/fr/create/redirects) dans `docs.json` pour tous les chemins de pages qui ont changé. Les redirections ne s’appliquent qu’au sein du projet qui les définit. +3. Supprimez le domaine personnalisé de chaque projet retiré afin de libérer le domaine. Consultez [Supprimer un domaine personnalisé](/fr/customize/custom-domain#remove-a-custom-domain). +4. Redirigez le trafic des sous-domaines retirés chez votre fournisseur DNS ou au niveau de votre couche d’hébergement. Mintlify ne peut pas rediriger un domaine qui n’est plus connecté à un projet. diff --git a/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx b/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx new file mode 100644 index 000000000..4cea93151 --- /dev/null +++ b/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx @@ -0,0 +1,25 @@ +--- +title: "_cf-custom-hostname TXT record stuck unverified" +description: "Why the verification TXT records stay unverified when your docs subpath proxy runs on Cloudflare, and why that is safe to ignore." +keywords: ["_cf-custom-hostname", "_acme-challenge", "TXT record unverified", "domain verification stuck", "pending validation", "proxied subpath", "Cloudflare Worker", "reverse proxy"] +--- + +If you host your documentation at a subpath behind a reverse proxy that runs on Cloudflare, such as a Cloudflare Worker that forwards `example.com/docs` to `.mintlify.site`, the [Custom domain setup](https://app.mintlify.com/settings/project/custom-domain) page still displays `_cf-custom-hostname` and `_acme-challenge` verification `TXT` records. In this setup, those records never show as verified, even if you add them at your DNS provider and click **Re-verify domain**. + +This is specific to proxies that run on Cloudflare. If your subpath proxy runs on a different platform, such as Vercel or a custom nginx reverse proxy, the `TXT` records verify through a standard DNS lookup and don't depend on where your traffic routes. If they stay unverified there, confirm you added them exactly as shown at your domain's authoritative DNS provider. + +## Why the records never verify + +Your domain is already proxied through Cloudflare, the same network Mintlify uses to verify custom hostnames. In this configuration, Cloudflare can't complete verification for the `TXT` records through a DNS lookup alone. It requires traffic for the hostname to route through its network to Mintlify first, the same requirement described in [Cloudflare-proxied domains](/customize/custom-domain#cloudflare-proxied-domains). + +When your own Cloudflare-based proxy serves the subpath, your domain's traffic terminates at your proxy and never reaches Mintlify's edge, so your setup can never meet this requirement. Your proxy terminates TLS with its own certificate and forwards requests to `.mintlify.site`, which already has a valid certificate, so the records stay unverified indefinitely. + +## What to do + +Nothing. The unverified status does not affect your documentation. To confirm your setup works, visit your subpath, like `example.com/docs`, and check that your documentation loads over HTTPS. + +Do not add the `CNAME` record shown in the dashboard. It routes all traffic for the domain to Mintlify and bypasses your proxy. You still need to enable the **Host at** toggle and add your domain with its base path in the dashboard so Mintlify builds your site at the correct subpath. See [Host docs at a subpath](/deploy/docs-subpath) and the [Cloudflare Workers guide](/deploy/cloudflare). + +## When verification does matter + +If your domain's traffic routes to Mintlify through the `CNAME`, the `TXT` records must verify before TLS provisioning completes. If your domain is proxied through Cloudflare (orange cloud), verification only completes after you update the `CNAME`. See [Cloudflare-proxied domains](/customize/custom-domain#cloudflare-proxied-domains). diff --git a/help-center/host-multiple-docs-sites-on-one-domain.mdx b/help-center/host-multiple-docs-sites-on-one-domain.mdx new file mode 100644 index 000000000..b5dc0e0ef --- /dev/null +++ b/help-center/host-multiple-docs-sites-on-one-domain.mdx @@ -0,0 +1,33 @@ +--- +title: "Can I host multiple docs sites on the same domain?" +description: "One custom domain connects to one Mintlify project. Combine products into a single site with path-based navigation or use separate subdomains." +keywords: ["multiple docs sites", "same domain", "multi-product documentation", "custom domain", "one project per domain", "subdomain per product", "consolidate docs sites"] +--- + +A custom domain connects to exactly one Mintlify project. You cannot point `example.com/product-a` at one project and `example.com/product-b` at another. If you try to add a domain that another project already holds, the dashboard returns a `Domain is already in use by another deployment in your organization` or `Domain is already claimed by another organization` error. See [Fix "Domain already claimed by another organization" error](/help-center/domain-already-claimed-by-another-organization). + +To document multiple products, choose one of these patterns. + +## One site with path-based navigation + +Combine all products into a single project and separate them with navigation. Each product gets its own URL path on the shared domain, like `docs.example.com/product-a` and `docs.example.com/product-b`. + +- Use [products](/organize/navigation#products), [tabs](/organize/navigation#tabs), or [dropdowns](/organize/navigation#dropdowns) in your `docs.json` to give each product a dedicated navigation division. +- If each product's documentation lives in its own Git repository, use a [multi-repository project](/deploy/multi-repo) to combine the repositories into one site with a URL path per repository. Multi-repository projects are available on Enterprise plans. + +This pattern keeps all products searchable from one place and requires only one custom domain. + +## Separate sites on separate subdomains + +Keep each product as its own project and give each project its own subdomain, like `docs-product-a.example.com` and `docs-product-b.example.com`. Add each subdomain as the [custom domain](/customize/custom-domain) for its project. + +Use this pattern when products need fully independent sites, such as separate teams, themes, or release processes. + +## Consolidate existing sites + +If you move separate sites into one project: + +1. Move the content into the combined project and organize it with navigation. +2. Add [redirects](/create/redirects) in `docs.json` for any page paths that changed. Redirects only apply within the project that defines them. +3. Remove the custom domain from each retired project so the domain is released. See [Remove a custom domain](/customize/custom-domain#remove-a-custom-domain). +4. Redirect traffic from retired subdomains at your DNS provider or hosting layer. Mintlify cannot redirect a domain that is no longer connected to a project. diff --git a/zh.json b/zh.json index a567ed2e5..1c999dd2a 100644 --- a/zh.json +++ b/zh.json @@ -474,7 +474,9 @@ "zh/help-center/migrate-from-confluence", "zh/help-center/migrate-docs-from-a-zip-export", "zh/help-center/agent-opens-pull-requests-against-deploy-branch", - "zh/help-center/publish-button-disabled-invalid-mdx" + "zh/help-center/publish-button-disabled-invalid-mdx", + "zh/help-center/host-multiple-docs-sites-on-one-domain", + "zh/help-center/cf-custom-hostname-txt-record-stuck-unverified" ] } ] diff --git a/zh/customize/custom-domain.mdx b/zh/customize/custom-domain.mdx index 0bc46f9b8..0863ebd44 100644 --- a/zh/customize/custom-domain.mdx +++ b/zh/customize/custom-domain.mdx @@ -39,7 +39,7 @@ keywords: ["自定义域名配置", "DNS 配置", "CNAME 记录", "TLS 证书", 如果你的域名流量指向 Mintlify，控制台将显示需要在你的域名提供商处添加的 DNS 记录。 -如果你只是将子路径代理到 Mintlify，控制台会改为显示反向代理的设置指南。请按照适用于你提供商的指南操作，并参阅 [在子路径下托管文档](/zh/deploy/docs-subpath) 获取更多信息。 +如果你只是将子路径代理到 Mintlify，请按照适用于你提供商的反向代理指南操作，而不要添加 `CNAME` 记录。参阅 [在子路径下托管文档](/zh/deploy/docs-subpath) 获取更多信息。如果你的代理运行在 Cloudflare 上，控制台中显示的验证 `TXT` 记录会保持未验证状态。这是预期行为。参见 [_cf-custom-hostname TXT 记录一直未验证](/zh/help-center/cf-custom-hostname-txt-record-stuck-unverified)。 你也可以从终端使用 [`mint add-domain `](/zh/cli/commands#mint-add-domain) 添加域名。该命令会在你的项目上注册该域名，并打印需要配置的 DNS 记录。 @@ -162,7 +162,7 @@ Mintlify 保留 `/.well-known/acme-challenge` 路径用于证书验证。你不 1. 在控制台中前往 [Custom domain setup](https://app.mintlify.com/settings/project/custom-domain) 页面。 2. 找到处于待验证状态的自定义域名。 -3. 选择 **Retry validation**。 +3. 选择 **Re-verify domain**。 请仅在确认 DNS 记录正确后再重新触发验证。使用错误的记录反复重试并不会加快验证。 diff --git a/zh/deploy/docs-subpath.mdx b/zh/deploy/docs-subpath.mdx index 339933d20..ff1bc87ad 100644 --- a/zh/deploy/docs-subpath.mdx +++ b/zh/deploy/docs-subpath.mdx @@ -26,6 +26,10 @@ boost: 3 - [Vercel](/zh/deploy/vercel)：使用重写规则将你的文档部署到你的子路径下。 - [Custom reverse proxy](/zh/deploy/reverse-proxy)：对于其他托管平台，设置反向代理以将你的文档部署到你的子路径下。 + + 当由你自己的代理为子路径提供服务时，请勿添加 [Custom domain setup](https://app.mintlify.com/settings/project/custom-domain) 页面上显示的 `CNAME` 记录。该记录会将该域名的所有流量路由到 Mintlify，并绕过你的代理。如果你的代理运行在 Cloudflare 上，验证 `TXT` 记录也会保持未验证状态。这是预期行为，不会影响你的文档。参见 [_cf-custom-hostname TXT 记录一直未验证](/zh/help-center/cf-custom-hostname-txt-record-stuck-unverified)。 + +
### 针对严格安全策略的额外配置
diff --git a/zh/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx b/zh/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx new file mode 100644 index 000000000..9f5dacec5 --- /dev/null +++ b/zh/help-center/cf-custom-hostname-txt-record-stuck-unverified.mdx @@ -0,0 +1,31 @@ +--- +title: "_cf-custom-hostname TXT 记录一直未验证" +description: "解释当你的子路径代理运行在 Cloudflare 上时，控制台中的验证 TXT 记录为何一直未验证，以及为何可以安全地忽略这一状态。" +keywords: ["_cf-custom-hostname", "_acme-challenge", "TXT record unverified", "域名验证卡住", "pending validation", "代理子路径", "Cloudflare Worker", "反向代理"] +--- + +如果你在运行于 Cloudflare 上的反向代理后面的子路径下托管文档（例如使用 Cloudflare Worker 将 `example.com/docs` 转发到 `.mintlify.site`），[Custom domain setup](https://app.mintlify.com/settings/project/custom-domain) 页面仍会显示 `_cf-custom-hostname` 和 `_acme-challenge` 验证 `TXT` 记录。在这种设置下，即使你在 DNS 提供商处添加了这些记录并点击 **Re-verify domain**，它们也永远不会显示为已验证。 + +这种情况仅针对运行在 Cloudflare 上的代理。如果你的子路径代理运行在其他平台上，例如 Vercel 或自定义的 nginx 反向代理，`TXT` 记录会通过标准的 DNS 查询进行验证，与你的流量路由到哪里无关。如果在这种情况下记录仍未验证，请确认你已按照页面显示的内容在域名的权威 DNS 提供商处准确添加了这些记录。 + +
+ ## 为什么这些记录永远无法验证 +
+ +你的域名已经通过 Cloudflare 代理，而这正是 Mintlify 用来验证自定义主机名的同一网络。在这种配置下，Cloudflare 无法仅通过 DNS 查询完成 `TXT` 记录的验证。它要求该主机名的流量必须先通过其网络路由到 Mintlify，这与[通过 Cloudflare 代理的域名](/zh/customize/custom-domain#cloudflare-proxied-domains)中描述的要求相同。 + +当由你自己基于 Cloudflare 的代理为子路径提供服务时，你域名的流量会在你的代理处终止，永远无法到达 Mintlify 的边缘节点，因此你的设置永远无法满足这一要求。你的代理使用自己的证书终止 TLS，并将请求转发到已经拥有有效证书的 `.mintlify.site`，因此这些记录会无限期地保持未验证状态。 + +
+ ## 该怎么做 +
+ +无需任何操作。未验证状态不会影响你的文档。要确认你的设置正常工作，请访问你的子路径（例如 `example.com/docs`），并检查你的文档是否通过 HTTPS 正常加载。 + +请勿添加控制台中显示的 `CNAME` 记录。它会将该域名的所有流量路由到 Mintlify，从而绕过你的代理。你仍然需要在控制台中启用 **Host at** 开关，并添加你的域名及其基础路径，以便 Mintlify 在正确的子路径下构建你的站点。参见[在子路径下托管文档](/zh/deploy/docs-subpath)和 [Cloudflare Workers 指南](/zh/deploy/cloudflare)。 + +
+ ## 什么情况下验证才重要 +
+ +如果你域名的流量通过 `CNAME` 路由到 Mintlify，则必须先完成 `TXT` 记录验证，TLS 签发才能完成。如果你的域名通过 Cloudflare 代理（橙色云图标），只有在你更新 `CNAME` 之后验证才会完成。参见[通过 Cloudflare 代理的域名](/zh/customize/custom-domain#cloudflare-proxied-domains)。 diff --git a/zh/help-center/host-multiple-docs-sites-on-one-domain.mdx b/zh/help-center/host-multiple-docs-sites-on-one-domain.mdx new file mode 100644 index 000000000..7c24ad89b --- /dev/null +++ b/zh/help-center/host-multiple-docs-sites-on-one-domain.mdx @@ -0,0 +1,39 @@ +--- +title: "能否在同一域名上托管多个文档站点？" +description: "一个自定义域名只能连接一个 Mintlify 项目。可通过基于路径的导航将多个产品合并为单个站点，或为每个产品使用独立的子域名。" +keywords: ["同一域名多个文档站点", "多产品文档", "custom domain", "一个域名一个项目", "每个产品一个子域名", "合并文档站点"] +--- + +自定义域名只会连接到一个 Mintlify 项目。你无法将 `example.com/product-a` 指向一个项目，而将 `example.com/product-b` 指向另一个项目。如果你尝试添加已被其他项目占用的域名，控制台会返回 `Domain is already in use by another deployment in your organization` 或 `Domain is already claimed by another organization` 错误。参见[修复 "Domain already claimed by another organization" 错误](/zh/help-center/domain-already-claimed-by-another-organization)。 + +若要为多个产品编写文档，请从以下模式中选择一种。 + +
+ ## 使用基于路径导航的单一站点 +
+ +将所有产品合并到一个项目中，并通过导航将它们区分开。每个产品在共享域名上拥有自己的 URL 路径，例如 `docs.example.com/product-a` 和 `docs.example.com/product-b`。 + +- 在你的 `docs.json` 中使用 [products](/zh/organize/navigation#products)、[tabs](/zh/organize/navigation#tabs) 或 [dropdowns](/zh/organize/navigation#dropdowns)，为每个产品提供专属的导航分区。 +- 如果每个产品的文档存放在各自的 Git 仓库中，请使用[多仓库项目](/zh/deploy/multi-repo)将这些仓库合并为一个站点，每个仓库对应一个 URL 路径。多仓库项目仅在 Enterprise 计划中可用。 + +这种模式让所有产品都可以在同一处搜索，并且只需要一个自定义域名。 + +
+ ## 在不同子域名上的独立站点 +
+ +让每个产品保持为独立的项目，并为每个项目分配自己的子域名，例如 `docs-product-a.example.com` 和 `docs-product-b.example.com`。将每个子域名添加为对应项目的[自定义域名](/zh/customize/custom-domain)。 + +当各产品需要完全独立的站点时（例如各自独立的团队、主题或发布流程），请使用这种模式。 + +
+ ## 合并现有站点 +
+ +如果你要将多个独立站点迁移到同一个项目： + +1. 将内容迁移到合并后的项目中，并通过导航进行组织。 +2. 在 `docs.json` 中为所有发生变化的页面路径添加[重定向](/zh/create/redirects)。重定向仅在定义它们的项目内生效。 +3. 从每个已停用的项目中移除自定义域名，以便释放该域名。参见[移除自定义域名](/zh/customize/custom-domain#remove-a-custom-domain)。 +4. 在你的 DNS 提供商或托管层重定向已停用子域名的流量。Mintlify 无法为不再连接到任何项目的域名进行重定向。