From dc9ed4ed8da30f6a274164caf04a368356873321 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 14 Aug 2026 16:11:18 +0000 Subject: [PATCH 1/3] docs: clarify docs.json location and add Auth0 OAuth help center article --- docs.json | 3 +- help-center/configure-oauth-with-auth0.mdx | 52 ++++++++++++++++++++++ organize/settings.mdx | 4 ++ 3 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 help-center/configure-oauth-with-auth0.mdx diff --git a/docs.json b/docs.json index 652ac7d90c..2d03903602 100644 --- a/docs.json +++ b/docs.json @@ -473,7 +473,8 @@ "group": "Help center", "pages": [ "help-center/openapi-url-fetch-fails-during-build", - "help-center/domain-already-claimed-by-another-organization" + "help-center/domain-already-claimed-by-another-organization", + "help-center/configure-oauth-with-auth0" ] } ] diff --git a/help-center/configure-oauth-with-auth0.mdx b/help-center/configure-oauth-with-auth0.mdx new file mode 100644 index 0000000000..9709ea5b0b --- /dev/null +++ b/help-center/configure-oauth-with-auth0.mdx @@ -0,0 +1,52 @@ +--- +title: "Configure OAuth 2.0 authentication with Auth0" +description: "Set up Auth0 as the OAuth 2.0 identity provider for a private Mintlify documentation site, including endpoint URLs, callback registration, and group-based access." +keywords: ["Auth0", "OAuth", "OAuth 2.0", "OIDC", "identity provider", "SSO", "private docs", "authentication"] +--- + +Auth0 is an OAuth 2.0 and OIDC-compliant identity provider, so it plugs directly into Mintlify's built-in OAuth 2.0 support. This page maps Auth0's endpoints and settings onto the fields in [Authentication setup](/deploy/authentication-setup#oauth-2-0). Use the canonical setup page for the full flow and refer here for the Auth0-specific values. + +OAuth 2.0 authentication is available on the Enterprise plan. + +## Prerequisites + +- An Auth0 tenant. Note your tenant domain, for example `your-tenant.us.auth0.com`. +- An Auth0 **Regular Web Application** created for your documentation site. +- The client ID and client secret for that application. + +## Map Auth0 to Mintlify's OAuth fields + +In your Mintlify dashboard, go to [Authentication](https://app.mintlify.com/products/authentication), set site visibility to **Private**, and choose **Custom** → **OAuth**. Fill in the fields with the following Auth0 values. Replace `YOUR_AUTH0_DOMAIN` with your tenant domain. + +| Mintlify field | Auth0 value | +|---|---| +| Authorization URL | `https://YOUR_AUTH0_DOMAIN/authorize` | +| Token URL | `https://YOUR_AUTH0_DOMAIN/oauth/token` | +| Client ID | Application client ID from Auth0 | +| Client Secret | Application client secret from Auth0 | +| Scopes | `openid profile email` (add more if your app needs them) | +| Info API URL (optional) | `https://YOUR_AUTH0_DOMAIN/userinfo` | +| Logout URL (optional) | `https://YOUR_AUTH0_DOMAIN/v2/logout?returnTo=` | + +Save the settings. Mintlify redeploys your site with the new authentication configuration. + +## Register the redirect URL in Auth0 + +Copy the **Redirect URL** shown in your Mintlify authentication settings and add it to your Auth0 application under **Application URIs → Allowed Callback URLs**. Save the Auth0 application. Without this step, Auth0 rejects the login flow. + +If you set a **Logout URL** in Mintlify, add the same return URL to your Auth0 application's **Allowed Logout URLs**. + +## Group-based access control + +To restrict pages to specific Auth0 users, you have two options. + +- **Token claims (recommended).** Add a groups claim to the ID token or access token with an [Auth0 Action](https://auth0.com/docs/customize/actions) and configure Mintlify to read it. See [Use groups from OAuth token claims](/deploy/authentication-setup#use-groups-from-oauth-token-claims). If you source groups from the ID token, keep `openid` in your scopes. +- **Info API URL.** Point Mintlify at `https://YOUR_AUTH0_DOMAIN/userinfo` or your own endpoint that returns user data in the [User data format](/deploy/authentication-setup#user-data-format). The endpoint must accept `Authorization: Bearer ` and return groups in the response. + +Then tag pages or navigation groups with a matching `groups` value so only members of that group can see them. + +## Troubleshooting + +- **Callback URL mismatch.** Auth0 blocks the login and shows a callback error. Confirm the redirect URL in Auth0's **Allowed Callback URLs** exactly matches the one shown in your Mintlify authentication settings, including protocol and trailing path. +- **Users log in but see no restricted content.** Your groups claim is not reaching Mintlify. Confirm the Auth0 Action adds the claim, that `source` in Mintlify matches the token you set it on (`id_token` or `access_token`), and that `groupsClaim` matches the claim name. +- **Logout does not redirect back.** Auth0 requires the `returnTo` URL in the logout link to be listed under **Allowed Logout URLs** on the application. diff --git a/organize/settings.mdx b/organize/settings.mdx index 233ade9257..e4016f8a60 100644 --- a/organize/settings.mdx +++ b/organize/settings.mdx @@ -6,6 +6,10 @@ keywords: ["docs.json", "configuration", "setup", "mint.json"] The `docs.json` file is the central configuration file for your Mintlify documentation site. It controls your site's global settings, including visual branding, navigation structure, integrations, API settings, and more. Think of it as the blueprint for your site. +## File location + +`docs.json` lives at the root of your documentation repository, alongside your content files. Edit it in the [web editor](/editor/index) or directly in your repository with your preferred IDE. + ## Required fields You must define four fields to build a working site. From 6739fd1520fd278e2a764ea3bee25089fbdf2a67 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 14 Aug 2026 16:18:11 +0000 Subject: [PATCH 2/3] docs: mirror docs.json location + Auth0 OAuth page into es, fr, zh --- es.json | 3 +- es/help-center/configure-oauth-with-auth0.mdx | 52 ++++++++++++++++ es/organize/settings.mdx | 6 ++ fr.json | 3 +- fr/help-center/configure-oauth-with-auth0.mdx | 52 ++++++++++++++++ fr/organize/settings.mdx | 6 ++ help-center/configure-oauth-with-auth0.mdx | 2 +- zh.json | 3 +- zh/help-center/configure-oauth-with-auth0.mdx | 62 +++++++++++++++++++ zh/organize/settings.mdx | 6 ++ 10 files changed, 191 insertions(+), 4 deletions(-) create mode 100644 es/help-center/configure-oauth-with-auth0.mdx create mode 100644 fr/help-center/configure-oauth-with-auth0.mdx create mode 100644 zh/help-center/configure-oauth-with-auth0.mdx diff --git a/es.json b/es.json index 8ba9c448ce..07a0df9954 100644 --- a/es.json +++ b/es.json @@ -451,7 +451,8 @@ "group": "Centro de ayuda", "pages": [ "es/help-center/openapi-url-fetch-fails-during-build", - "es/help-center/domain-already-claimed-by-another-organization" + "es/help-center/domain-already-claimed-by-another-organization", + "es/help-center/configure-oauth-with-auth0" ] } ] diff --git a/es/help-center/configure-oauth-with-auth0.mdx b/es/help-center/configure-oauth-with-auth0.mdx new file mode 100644 index 0000000000..d2178b5c50 --- /dev/null +++ b/es/help-center/configure-oauth-with-auth0.mdx @@ -0,0 +1,52 @@ +--- +title: "Configurar la autenticación OAuth 2.0 con Auth0" +description: "Configura Auth0 como proveedor de identidad OAuth 2.0 para un sitio privado de documentación de Mintlify, incluyendo las URLs de los endpoints, el registro del callback y el control de acceso basado en grupos." +keywords: ["Auth0", "OAuth", "OAuth 2.0", "OIDC", "identity provider", "SSO", "private docs", "authentication"] +--- + +Auth0 es un proveedor de identidad compatible con OAuth 2.0 y OIDC, por lo que se integra directamente con el soporte nativo de OAuth 2.0 de Mintlify. Esta página asigna los endpoints y ajustes de Auth0 a los campos de [Configuración de autenticación](/es/deploy/authentication-setup#oauth-2-0). Usa la página canónica de configuración para el flujo completo y consulta esta para los valores específicos de Auth0. + +La autenticación OAuth 2.0 está disponible en el plan Enterprise. + +## Requisitos previos + +- Un tenant de Auth0. Anota el dominio de tu tenant, por ejemplo `your-tenant.us.auth0.com`. +- Una **Regular Web Application** de Auth0 creada para tu sitio de documentación. +- El client ID y el client secret de esa aplicación. + +## Asigna Auth0 a los campos de OAuth de Mintlify + +En tu panel de Mintlify, ve a [Authentication](https://app.mintlify.com/products/authentication), define la visibilidad del sitio como **Private** y elige **Custom** → **OAuth**. Rellena los campos con los siguientes valores de Auth0. Reemplaza `YOUR_AUTH0_DOMAIN` con el dominio de tu tenant. + +| Campo de Mintlify | Valor de Auth0 | +|---|---| +| Authorization URL | `https://YOUR_AUTH0_DOMAIN/authorize` | +| Token URL | `https://YOUR_AUTH0_DOMAIN/oauth/token` | +| Client ID | Client ID de la aplicación en Auth0 | +| Client Secret | Client secret de la aplicación en Auth0 | +| Scopes | `openid profile email` (añade más si tu aplicación los necesita) | +| Info API URL (opcional) | `https://YOUR_AUTH0_DOMAIN/userinfo` | +| Logout URL (opcional) | `https://YOUR_AUTH0_DOMAIN/v2/logout?returnTo=` | + +Guarda la configuración. Mintlify vuelve a desplegar tu sitio con la nueva configuración de autenticación. + +## Registra la URL de redirección en Auth0 + +Copia la **Redirect URL** que aparece en la configuración de autenticación de Mintlify y añádela a tu aplicación de Auth0 en **Application URIs → Allowed Callback URLs**. Guarda la aplicación de Auth0. Sin este paso, Auth0 rechaza el flujo de inicio de sesión. + +Si configuras una **Logout URL** en Mintlify, añade la misma URL de retorno a los **Allowed Logout URLs** de tu aplicación de Auth0. + +## Control de acceso basado en grupos + +Para restringir páginas a usuarios específicos de Auth0, tienes dos opciones. + +- **Claims del token (recomendado).** Añade un claim de grupos al ID token o al access token mediante una [Auth0 Action](https://auth0.com/docs/customize/actions) y configura Mintlify para leerlo. Consulta [Usar grupos desde claims del token de OAuth](/es/deploy/authentication-setup#use-groups-from-oauth-token-claims). Si obtienes los grupos del ID token, mantén `openid` en tus scopes. +- **Info API URL.** Apunta Mintlify a `https://YOUR_AUTH0_DOMAIN/userinfo` o a tu propio endpoint que devuelva los datos del usuario en el [formato de datos de usuario](/es/deploy/authentication-setup#user-data-format). El endpoint debe aceptar `Authorization: Bearer ` y devolver los grupos en la respuesta. + +Luego etiqueta las páginas o grupos de navegación con un valor `groups` que coincida para que solo los miembros de ese grupo puedan verlos. + +## Solución de problemas + +- **La URL de callback no coincide.** Auth0 bloquea el inicio de sesión y muestra un error de callback. Confirma que la URL de redirección en los **Allowed Callback URLs** de Auth0 coincide exactamente con la que aparece en la configuración de autenticación de Mintlify, incluyendo el protocolo y la ruta final. +- **Los usuarios inician sesión pero no ven contenido restringido.** Tu claim de grupos no está llegando a Mintlify. Confirma que la Auth0 Action añade el claim, que el `source` en Mintlify coincide con el token en el que lo configuraste (`id_token` o `access_token`) y que `groupsClaim` coincide con el nombre del claim. +- **El cierre de sesión no redirige de vuelta.** Auth0 requiere que la URL `returnTo` del enlace de cierre de sesión esté listada en los **Allowed Logout URLs** de la aplicación. diff --git a/es/organize/settings.mdx b/es/organize/settings.mdx index a47e0eea38..eb47e68364 100644 --- a/es/organize/settings.mdx +++ b/es/organize/settings.mdx @@ -6,6 +6,12 @@ keywords: ["docs.json", "configuration", "setup", "mint.json"] El archivo `docs.json` es el archivo de configuración central de tu sitio de documentación Mintlify. Controla la configuración global de tu sitio, incluyendo la identidad visual, la estructura de navegación, las integraciones, la configuración de la API y más. Piensa en él como el plano de tu sitio. +
+## Ubicación del archivo +
+ +`docs.json` se ubica en la raíz del repositorio de tu documentación, junto con tus archivos de contenido. Edítalo en el [editor web](/es/editor/index) o directamente en tu repositorio con tu IDE preferido. + ## Campos obligatorios Debes definir cuatro campos para construir un sitio funcional. diff --git a/fr.json b/fr.json index e85486f530..731ed9eeb0 100644 --- a/fr.json +++ b/fr.json @@ -451,7 +451,8 @@ "group": "Centre d'aide", "pages": [ "fr/help-center/openapi-url-fetch-fails-during-build", - "fr/help-center/domain-already-claimed-by-another-organization" + "fr/help-center/domain-already-claimed-by-another-organization", + "fr/help-center/configure-oauth-with-auth0" ] } ] diff --git a/fr/help-center/configure-oauth-with-auth0.mdx b/fr/help-center/configure-oauth-with-auth0.mdx new file mode 100644 index 0000000000..19608754c8 --- /dev/null +++ b/fr/help-center/configure-oauth-with-auth0.mdx @@ -0,0 +1,52 @@ +--- +title: "Configurer l'authentification OAuth 2.0 avec Auth0" +description: "Configurez Auth0 comme fournisseur d'identité OAuth 2.0 pour un site de documentation Mintlify privé, y compris les URL d'endpoints, l'enregistrement du callback et le contrôle d'accès basé sur les groupes." +keywords: ["Auth0", "OAuth", "OAuth 2.0", "OIDC", "identity provider", "SSO", "private docs", "authentication"] +--- + +Auth0 est un fournisseur d'identité conforme à OAuth 2.0 et OIDC, il s'intègre donc directement à la prise en charge native d'OAuth 2.0 de Mintlify. Cette page met en correspondance les endpoints et les paramètres d'Auth0 avec les champs de la page [Configuration de l'authentification](/fr/deploy/authentication-setup#oauth-2-0). Utilisez la page de configuration canonique pour le flux complet et consultez celle-ci pour les valeurs propres à Auth0. + +L'authentification OAuth 2.0 est disponible sur le plan Enterprise. + +## Prérequis + +- Un tenant Auth0. Notez son domaine, par exemple `your-tenant.us.auth0.com`. +- Une **Regular Web Application** Auth0 créée pour votre site de documentation. +- L'identifiant client et le secret client de cette application. + +## Mettre en correspondance Auth0 avec les champs OAuth de Mintlify + +Dans votre tableau de bord Mintlify, accédez à [Authentication](https://app.mintlify.com/products/authentication), définissez la visibilité du site sur **Private**, puis choisissez **Custom** → **OAuth**. Renseignez les champs avec les valeurs Auth0 suivantes. Remplacez `YOUR_AUTH0_DOMAIN` par le domaine de votre tenant. + +| Champ Mintlify | Valeur Auth0 | +|---|---| +| Authorization URL | `https://YOUR_AUTH0_DOMAIN/authorize` | +| Token URL | `https://YOUR_AUTH0_DOMAIN/oauth/token` | +| Client ID | Identifiant client de l'application depuis Auth0 | +| Client Secret | Secret client de l'application depuis Auth0 | +| Scopes | `openid profile email` (ajoutez-en d'autres si votre application en a besoin) | +| Info API URL (facultatif) | `https://YOUR_AUTH0_DOMAIN/userinfo` | +| Logout URL (facultatif) | `https://YOUR_AUTH0_DOMAIN/v2/logout?returnTo=` | + +Enregistrez les paramètres. Mintlify redéploie votre site avec la nouvelle configuration d'authentification. + +## Enregistrer l'URL de redirection dans Auth0 + +Copiez la **Redirect URL** affichée dans vos paramètres d'authentification Mintlify et ajoutez-la à votre application Auth0 sous **Application URIs → Allowed Callback URLs**. Enregistrez l'application Auth0. Sans cette étape, Auth0 rejette le flux de connexion. + +Si vous avez défini une **Logout URL** dans Mintlify, ajoutez la même URL de retour aux **Allowed Logout URLs** de votre application Auth0. + +## Contrôle d'accès basé sur les groupes + +Pour restreindre certaines pages à des utilisateurs Auth0 spécifiques, vous avez deux options. + +- **Claims des jetons (recommandé).** Ajoutez un claim de groupes à l'ID token ou à l'access token avec une [Auth0 Action](https://auth0.com/docs/customize/actions) et configurez Mintlify pour le lire. Voir [Utiliser les groupes issus des claims des jetons OAuth](/fr/deploy/authentication-setup#use-groups-from-oauth-token-claims). Si vous récupérez les groupes depuis l'ID token, conservez `openid` dans vos scopes. +- **Info API URL.** Pointez Mintlify vers `https://YOUR_AUTH0_DOMAIN/userinfo` ou vers votre propre endpoint renvoyant des données utilisateur au [format des données utilisateur](/fr/deploy/authentication-setup#user-data-format). L'endpoint doit accepter `Authorization: Bearer ` et renvoyer les groupes dans la réponse. + +Ensuite, taguez les pages ou les groupes de navigation avec une valeur `groups` correspondante afin que seuls les membres de ce groupe puissent les voir. + +## Dépannage + +- **Callback URL mismatch.** Auth0 bloque la connexion et affiche une erreur de callback. Vérifiez que l'URL de redirection dans les **Allowed Callback URLs** d'Auth0 correspond exactement à celle affichée dans vos paramètres d'authentification Mintlify, y compris le protocole et le chemin final. +- **Les utilisateurs se connectent mais ne voient aucun contenu restreint.** Votre claim de groupes n'atteint pas Mintlify. Vérifiez que l'Auth0 Action ajoute bien le claim, que la `source` définie dans Mintlify correspond au jeton sur lequel vous l'avez placé (`id_token` ou `access_token`), et que `groupsClaim` correspond au nom du claim. +- **La déconnexion ne redirige pas en arrière.** Auth0 exige que l'URL `returnTo` du lien de déconnexion soit listée sous les **Allowed Logout URLs** de l'application. diff --git a/fr/organize/settings.mdx b/fr/organize/settings.mdx index 80cf907b28..b0565a89d5 100644 --- a/fr/organize/settings.mdx +++ b/fr/organize/settings.mdx @@ -6,6 +6,12 @@ keywords: ["docs.json", "configuration", "setup", "mint.json"] Le fichier `docs.json` est le fichier de configuration central de votre site de documentation Mintlify. Il contrôle les paramètres globaux de votre site, y compris l'identité visuelle, la structure de navigation, les intégrations, les paramètres d'API et plus encore. Considérez-le comme le plan directeur de votre site. +
+## Emplacement du fichier +
+ +`docs.json` se trouve à la racine de votre dépôt de documentation, aux côtés de vos fichiers de contenu. Modifiez-le dans l'[éditeur web](/fr/editor/index) ou directement dans votre dépôt avec votre IDE préféré. + ## Champs obligatoires Vous devez définir quatre champs pour construire un site fonctionnel. diff --git a/help-center/configure-oauth-with-auth0.mdx b/help-center/configure-oauth-with-auth0.mdx index 9709ea5b0b..db989278ba 100644 --- a/help-center/configure-oauth-with-auth0.mdx +++ b/help-center/configure-oauth-with-auth0.mdx @@ -1,6 +1,6 @@ --- title: "Configure OAuth 2.0 authentication with Auth0" -description: "Set up Auth0 as the OAuth 2.0 identity provider for a private Mintlify documentation site, including endpoint URLs, callback registration, and group-based access." +description: "Set up Auth0 as the OAuth 2.0 identity provider for a private Mintlify docs site: endpoint URLs, callback registration, and group-based access." keywords: ["Auth0", "OAuth", "OAuth 2.0", "OIDC", "identity provider", "SSO", "private docs", "authentication"] --- diff --git a/zh.json b/zh.json index 4c5ba09662..f9300374c1 100644 --- a/zh.json +++ b/zh.json @@ -451,7 +451,8 @@ "group": "帮助中心", "pages": [ "zh/help-center/openapi-url-fetch-fails-during-build", - "zh/help-center/domain-already-claimed-by-another-organization" + "zh/help-center/domain-already-claimed-by-another-organization", + "zh/help-center/configure-oauth-with-auth0" ] } ] diff --git a/zh/help-center/configure-oauth-with-auth0.mdx b/zh/help-center/configure-oauth-with-auth0.mdx new file mode 100644 index 0000000000..bb6f65b1cc --- /dev/null +++ b/zh/help-center/configure-oauth-with-auth0.mdx @@ -0,0 +1,62 @@ +--- +title: "使用 Auth0 配置 OAuth 2.0 身份验证" +description: "为私有 Mintlify 文档站点将 Auth0 设置为 OAuth 2.0 身份提供方，包括端点 URL、回调注册和基于用户组的访问控制。" +keywords: ["Auth0", "OAuth", "OAuth 2.0", "OIDC", "identity provider", "SSO", "private docs", "authentication"] +--- + +Auth0 是一个兼容 OAuth 2.0 和 OIDC 的身份提供方，因此可以直接接入 Mintlify 内置的 OAuth 2.0 支持。本页将 Auth0 的端点和设置映射到[身份验证设置](/zh/deploy/authentication-setup#oauth-2-0)中的字段。完整流程请参考对应的官方设置页面，本页仅提供 Auth0 特定的取值。 + +OAuth 2.0 身份验证在 Enterprise 方案中可用。 + +
+## 前提条件 +
+ +- 一个 Auth0 租户。记下你的租户域名，例如 `your-tenant.us.auth0.com`。 +- 为你的文档站点创建的 Auth0 **Regular Web Application**。 +- 该应用的 client ID 和 client secret。 + +
+## 将 Auth0 映射到 Mintlify 的 OAuth 字段 +
+ +在 Mintlify 控制台中，进入[身份验证](https://app.mintlify.com/products/authentication)，将站点可见性设置为 **Private**，然后选择 **Custom** → **OAuth**。使用以下 Auth0 的取值填写各字段。将 `YOUR_AUTH0_DOMAIN` 替换为你的租户域名。 + +| Mintlify 字段 | Auth0 取值 | +|---|---| +| Authorization URL | `https://YOUR_AUTH0_DOMAIN/authorize` | +| Token URL | `https://YOUR_AUTH0_DOMAIN/oauth/token` | +| Client ID | 来自 Auth0 的应用 client ID | +| Client Secret | 来自 Auth0 的应用 client secret | +| Scopes | `openid profile email`（如果你的应用需要，可添加更多） | +| Info API URL（可选） | `https://YOUR_AUTH0_DOMAIN/userinfo` | +| Logout URL（可选） | `https://YOUR_AUTH0_DOMAIN/v2/logout?returnTo=` | + +保存设置。Mintlify 会使用新的身份验证配置重新部署你的站点。 + +
+## 在 Auth0 中注册重定向 URL +
+ +复制 Mintlify 身份验证设置中显示的 **Redirect URL**，并在 Auth0 应用的 **Application URIs → Allowed Callback URLs** 中添加该地址。保存 Auth0 应用。若未完成此步骤，Auth0 将拒绝登录流程。 + +如果你在 Mintlify 中设置了 **Logout URL**，请把相同的返回地址添加到 Auth0 应用的 **Allowed Logout URLs**。 + +
+## 基于用户组的访问控制 +
+ +若要将页面限制给特定的 Auth0 用户访问，有两种方式。 + +- **令牌声明（推荐）。** 使用 [Auth0 Action](https://auth0.com/docs/customize/actions) 在 ID 令牌或访问令牌中添加 groups 声明，并配置 Mintlify 读取它。参见[使用 OAuth 令牌声明中的用户组](/zh/deploy/authentication-setup#use-groups-from-oauth-token-claims)。如果你从 ID 令牌中获取用户组，请在 scopes 中保留 `openid`。 +- **Info API URL。** 让 Mintlify 指向 `https://YOUR_AUTH0_DOMAIN/userinfo` 或你自己的端点，该端点需按[用户数据格式](/zh/deploy/authentication-setup#user-data-format)返回用户数据。端点必须接受 `Authorization: Bearer `，并在响应中返回用户组。 + +然后为页面或导航分组标记匹配的 `groups` 值，这样只有属于该分组的成员才能看到它们。 + +
+## 疑难解答 +
+ +- **回调 URL 不匹配。** Auth0 会阻止登录并显示回调错误。请确认 Auth0 **Allowed Callback URLs** 中的 redirect URL 与 Mintlify 身份验证设置中显示的地址完全一致，包括协议和结尾路径。 +- **用户能登录但看不到受限内容。** 你的 groups 声明没有传到 Mintlify。请确认 Auth0 Action 已添加该声明，Mintlify 中的 `source` 与你写入声明的令牌（`id_token` 或 `access_token`）一致，并且 `groupsClaim` 与声明名称匹配。 +- **登出后未跳回。** Auth0 要求登出链接中的 `returnTo` URL 已列入该应用的 **Allowed Logout URLs**。 diff --git a/zh/organize/settings.mdx b/zh/organize/settings.mdx index 077b430a90..e00878468d 100644 --- a/zh/organize/settings.mdx +++ b/zh/organize/settings.mdx @@ -6,6 +6,12 @@ keywords: ["docs.json", "配置", "设置", "mint.json"] `docs.json` 文件是 Mintlify 文档站点的核心配置文件。它控制站点的全局设置，包括视觉品牌、导航结构、集成、API 设置等。可以把它看作站点的蓝图。 +
+## 文件位置 +
+ +`docs.json` 位于你的文档仓库根目录，与内容文件放在一起。你可以在[网页编辑器](/zh/editor/index)中编辑，也可以在仓库中使用你喜欢的 IDE 直接编辑。 + ## 必需字段 你必须定义四个字段才能构建一个可用的站点。 From 74df4711998c1dc8ffe0f7366b93fdc95029047c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 14 Aug 2026 14:35:42 -0700 Subject: [PATCH 3/3] Apply suggestion from @ethanpalm --- organize/settings.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/organize/settings.mdx b/organize/settings.mdx index e4016f8a60..55274b3644 100644 --- a/organize/settings.mdx +++ b/organize/settings.mdx @@ -8,7 +8,7 @@ The `docs.json` file is the central configuration file for your Mintlify documen ## File location -`docs.json` lives at the root of your documentation repository, alongside your content files. Edit it in the [web editor](/editor/index) or directly in your repository with your preferred IDE. +Store your `docs.json` file at the root of your documentation repository. If you have a monorepo, store your `docs.json` at the root of your documentation directory. ## Required fields