+ ## Restringir el acceso al dashboard por IP
+
+
+Utiliza la lista de IP permitidas para restringir el acceso al dashboard a un conjunto de redes de confianza. Cuando la lista tiene una o más entradas, solo las solicitudes desde esas IP o rangos pueden iniciar sesión o utilizar el dashboard. Cuando la lista está vacía, el dashboard es accesible desde cualquier dirección IP.
+
+
## Registro de auditoría
@@ -58,3 +76,4 @@ Los cambios en la configuración de seguridad de sesión se registran en los [re
- `org.session_security_session_duration_deleted`
- `org.session_security_max_session_lifetime_updated`
- `org.session_security_max_session_lifetime_deleted`
+- `org.session_security_ip_allowlist_updated`
diff --git a/fr/dashboard/session-security.mdx b/fr/dashboard/session-security.mdx
index 641934b10e..6862fc640c 100644
--- a/fr/dashboard/session-security.mdx
+++ b/fr/dashboard/session-security.mdx
@@ -1,7 +1,7 @@
---
title: "Sécurité des sessions"
-description: "Configurez le délai d'inactivité et la durée de vie maximale des sessions du Dashboard pour votre organisation afin d'appliquer des politiques d'authentification plus strictes."
-keywords: ["session", "timeout", "authentication", "security", "SSO"]
+description: "Configurez les délais d'expiration des sessions du Dashboard, la durée de vie maximale des sessions et une liste d'autorisation d'adresses IP afin d'appliquer des politiques d'authentification et d'accès réseau plus strictes."
+keywords: ["session", "timeout", "authentication", "security", "SSO", "IP allowlist"]
---
+ ## Restreindre l'accès au Dashboard par IP
+
+
+Utilisez la liste d'autorisation d'adresses IP pour restreindre l'accès au Dashboard à un ensemble de réseaux de confiance. Lorsque la liste contient une ou plusieurs entrées, seules les requêtes provenant de ces adresses IP ou plages peuvent se connecter au Dashboard ou l'utiliser. Lorsque la liste est vide, le Dashboard est accessible depuis n'importe quelle adresse IP.
+
+
## Journalisation d'audit
@@ -58,3 +76,4 @@ Les modifications apportées aux paramètres de sécurité des sessions sont enr
- `org.session_security_session_duration_deleted`
- `org.session_security_max_session_lifetime_updated`
- `org.session_security_max_session_lifetime_deleted`
+- `org.session_security_ip_allowlist_updated`
diff --git a/zh/dashboard/session-security.mdx b/zh/dashboard/session-security.mdx
index 810144c23e..51cd8a839a 100644
--- a/zh/dashboard/session-security.mdx
+++ b/zh/dashboard/session-security.mdx
@@ -1,7 +1,7 @@
---
title: "会话安全"
-description: "为你的组织配置控制台会话空闲超时和最大会话生命周期，以强制执行更严格的身份验证策略。"
-keywords: ["session", "timeout", "authentication", "security", "SSO"]
+description: "配置控制台会话超时、最大会话生命周期以及 IP 允许列表，以强制执行更严格的身份验证和网络访问策略。"
+keywords: ["session", "timeout", "authentication", "security", "SSO", "IP allowlist"]
---
+ ## 通过 IP 限制控制台访问
+
+
+使用 IP 允许列表将控制台访问限制为一组受信任的网络。当允许列表中包含一个或多个条目时，只有来自这些 IP 或范围的请求才能登录或使用控制台。当允许列表为空时，可从任何 IP 地址访问控制台。
+
+
## 审计日志
@@ -58,3 +76,4 @@ Enterprise 管理员可以要求控制台用户按照符合组织安全策略的
- `org.session_security_session_duration_deleted`
- `org.session_security_max_session_lifetime_updated`
- `org.session_security_max_session_lifetime_deleted`
+- `org.session_security_ip_allowlist_updated`
From 2b0269a704efcdeefad5aa44b269b9690942d22a Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Wed, 8 Jul 2026 23:26:57 +0000
Subject: [PATCH 4/5] docs: move session lifetime and IP allowlist config under
Policies tab
---
dashboard/session-security.mdx | 24 +++++++++++++-----------
es/dashboard/session-security.mdx | 28 +++++++++++++++-------------
fr/dashboard/session-security.mdx | 28 +++++++++++++++-------------
zh/dashboard/session-security.mdx | 28 +++++++++++++++-------------
4 files changed, 58 insertions(+), 50 deletions(-)
diff --git a/dashboard/session-security.mdx b/dashboard/session-security.mdx
index 25bf2dbf04..45039f63f9 100644
--- a/dashboard/session-security.mdx
+++ b/dashboard/session-security.mdx
@@ -10,20 +10,22 @@ keywords: ["session", "timeout", "authentication", "security", "SSO", "IP allowl
Enterprise admins can require dashboard users to reauthenticate on a schedule that fits your organization's security policies. Two independent controls determine when a dashboard session ends:
-- **Idle session duration**: How long a session can remain inactive before the user is signed out.
+- **Idle session timeout**: How long a session can remain inactive before the user is signed out.
- **Maximum session lifetime**: The absolute lifetime of a session, regardless of activity. When exceeded, the user is signed out and must reauthenticate.
-If a setting is not configured, Mintlify's default applies. Both settings accept values between **5 minutes and 14 days** (20,160 minutes).
+Each setting has its own enable toggle. If a setting is disabled, Mintlify's default applies. Both settings accept values between **5 minutes and 14 days** (20,160 minutes).
-## Configure session duration
+## Configure session lifetimes
-To review or change session security settings, go to the [Single Sign-On](https://app.mintlify.com/settings/organization/sso) page of your dashboard.
+To review or change session lifetimes, go to the **Policies** tab of the [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) page in your dashboard.
-### Idle session duration
+For each setting, use the toggle to enable or disable it, enter a value, choose a unit (minutes, hours, days, or weeks for maximum lifetime; minutes, hours, or days for idle timeout), and select **Save**. Disabling a setting and saving clears it so Mintlify's default takes over.
-The idle session duration controls how long a session can remain inactive before it expires. Any dashboard request from the user resets the idle timer.
+### Idle session timeout
-Use a shorter idle duration to reduce the risk of unattended sessions being used by someone other than the signed-in user, for example on shared or unlocked devices.
+The idle session timeout controls how long a session can remain inactive before it expires. Any dashboard request from the user resets the idle timer.
+
+Use a shorter idle timeout to reduce the risk of unattended sessions being used by someone other than the signed-in user, for example on shared or unlocked devices.
### Maximum session lifetime
@@ -35,10 +37,10 @@ Use a maximum lifetime to guarantee that users reauthenticate on a regular caden
The two settings apply independently. A user's session ends at whichever limit is reached first:
-- If the user is inactive for longer than the **idle session duration**, the session ends.
+- If the user is inactive for longer than the **idle session timeout**, the session ends.
- If the **maximum session lifetime** elapses since sign-in, the session ends even if the user is active.
-For example, if you set the idle duration to 1 hour and the maximum lifetime to 8 hours, an actively working user is signed out after 8 hours, and an idle user is signed out after 1 hour.
+For example, if you set the idle timeout to 1 hour and the maximum lifetime to 8 hours, an actively working user is signed out after 8 hours, and an idle user is signed out after 1 hour.
## Restrict dashboard access by IP
@@ -48,13 +50,13 @@ Use the IP allowlist to restrict dashboard access to a set of trusted networks.
If your current IP address is not on the allowlist, you can lock yourself out of the dashboard. Confirm your IP is included before saving.
-To configure the allowlist, go to the [Network access](https://app.mintlify.com/settings/organization/network-access) page of your dashboard.
+To configure the allowlist, go to the **Policies** tab of the [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) page in your dashboard.
- **Add an entry**: Enter an IPv4 or IPv6 address, or a CIDR range (for example, `203.0.113.7` or `10.0.0.0/8`), then select **Add**. Adding the first entry enables the allowlist.
- **Remove an entry**: Select the **×** on any entry. Removing the last entry disables the allowlist.
- **Check your IP**: Your current IP address is shown below the entry list so you can confirm it is covered before saving changes.
-The status badge next to **Allowed IP addresses** shows **Active** when at least one entry is present and **Disabled** when the list is empty.
+The status badge next to **IP allowlist** shows **Active** when at least one entry is present and **Disabled** when the list is empty.
## Audit logging
diff --git a/es/dashboard/session-security.mdx b/es/dashboard/session-security.mdx
index 2410d71f09..13308ffc93 100644
--- a/es/dashboard/session-security.mdx
+++ b/es/dashboard/session-security.mdx
@@ -10,24 +10,26 @@ keywords: ["session", "timeout", "authentication", "security", "SSO", "IP allowl
Los administradores de Enterprise pueden exigir que los usuarios del dashboard vuelvan a autenticarse siguiendo una programación que se ajuste a las políticas de seguridad de tu organización. Dos controles independientes determinan cuándo finaliza una sesión del dashboard:
-- **Duración de sesión inactiva**: Cuánto tiempo puede permanecer inactiva una sesión antes de que se cierre la sesión del usuario.
+- **Tiempo de espera de sesión inactiva**: Cuánto tiempo puede permanecer inactiva una sesión antes de que se cierre la sesión del usuario.
- **Duración máxima de sesión**: La duración absoluta de una sesión, independientemente de la actividad. Cuando se supera, se cierra la sesión del usuario y debe volver a autenticarse.
-Si no se configura un ajuste, se aplica el valor predeterminado de Mintlify. Ambos ajustes aceptan valores entre **5 minutos y 14 días** (20.160 minutos).
+Cada ajuste tiene su propio interruptor de activación. Si un ajuste está deshabilitado, se aplica el valor predeterminado de Mintlify. Ambos ajustes aceptan valores entre **5 minutos y 14 días** (20.160 minutos).
-
- ## Configurar la duración de la sesión
+
+ ## Configurar duraciones de sesión
-Para revisar o cambiar la configuración de seguridad de sesión, ve a la página de [Single Sign-On](https://app.mintlify.com/settings/organization/sso) de tu dashboard.
+Para revisar o cambiar las duraciones de sesión, ve a la pestaña **Policies** de la página [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) de tu dashboard.
-
- ### Duración de sesión inactiva
+Para cada ajuste, usa el interruptor para habilitarlo o deshabilitarlo, introduce un valor, elige una unidad (minutos, horas, días o semanas para la duración máxima; minutos, horas o días para el tiempo de espera de inactividad) y selecciona **Save**. Al deshabilitar un ajuste y guardar, se borra para que se aplique el valor predeterminado de Mintlify.
+
+
+ ### Tiempo de espera de sesión inactiva
-La duración de sesión inactiva controla cuánto tiempo puede permanecer inactiva una sesión antes de que expire. Cualquier solicitud del usuario al dashboard reinicia el temporizador de inactividad.
+El tiempo de espera de sesión inactiva controla cuánto tiempo puede permanecer inactiva una sesión antes de que expire. Cualquier solicitud del usuario al dashboard reinicia el temporizador de inactividad.
-Utiliza una duración de inactividad más corta para reducir el riesgo de que sesiones desatendidas sean utilizadas por alguien que no sea el usuario que inició sesión, por ejemplo en dispositivos compartidos o desbloqueados.
+Utiliza un tiempo de espera de inactividad más corto para reducir el riesgo de que sesiones desatendidas sean utilizadas por alguien que no sea el usuario que inició sesión, por ejemplo en dispositivos compartidos o desbloqueados.
### Duración máxima de sesión
@@ -43,10 +45,10 @@ Utiliza una duración máxima para garantizar que los usuarios vuelvan a autenti
Los dos ajustes se aplican de forma independiente. La sesión de un usuario finaliza cuando se alcanza el primero de los límites:
-- Si el usuario permanece inactivo durante más tiempo que la **duración de sesión inactiva**, la sesión finaliza.
+- Si el usuario permanece inactivo durante más tiempo que el **tiempo de espera de sesión inactiva**, la sesión finaliza.
- Si transcurre la **duración máxima de sesión** desde el inicio de sesión, la sesión finaliza incluso si el usuario está activo.
-Por ejemplo, si estableces la duración de inactividad en 1 hora y la duración máxima en 8 horas, un usuario que esté trabajando activamente cerrará sesión después de 8 horas, y un usuario inactivo cerrará sesión después de 1 hora.
+Por ejemplo, si estableces el tiempo de espera de inactividad en 1 hora y la duración máxima en 8 horas, un usuario que esté trabajando activamente cerrará sesión después de 8 horas, y un usuario inactivo cerrará sesión después de 1 hora.
## Restringir el acceso al dashboard por IP
@@ -58,13 +60,13 @@ Utiliza la lista de IP permitidas para restringir el acceso al dashboard a un co
Si tu dirección IP actual no está en la lista de IP permitidas, puedes bloquearte a ti mismo el acceso al dashboard. Confirma que tu IP esté incluida antes de guardar.
-Para configurar la lista de IP permitidas, ve a la página de [Acceso a la red](https://app.mintlify.com/settings/organization/network-access) de tu dashboard.
+Para configurar la lista de IP permitidas, ve a la pestaña **Policies** de la página [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) de tu dashboard.
- **Añadir una entrada**: Introduce una dirección IPv4 o IPv6, o un rango CIDR (por ejemplo, `203.0.113.7` o `10.0.0.0/8`), y luego selecciona **Add**. Añadir la primera entrada habilita la lista de IP permitidas.
- **Eliminar una entrada**: Selecciona la **×** en cualquier entrada. Eliminar la última entrada deshabilita la lista de IP permitidas.
- **Comprueba tu IP**: Tu dirección IP actual se muestra debajo de la lista de entradas para que puedas confirmar que está cubierta antes de guardar los cambios.
-La insignia de estado junto a **Allowed IP addresses** muestra **Active** cuando hay al menos una entrada presente y **Disabled** cuando la lista está vacía.
+La insignia de estado junto a **IP allowlist** muestra **Active** cuando hay al menos una entrada presente y **Disabled** cuando la lista está vacía.
## Registro de auditoría
diff --git a/fr/dashboard/session-security.mdx b/fr/dashboard/session-security.mdx
index 6862fc640c..f979438f0f 100644
--- a/fr/dashboard/session-security.mdx
+++ b/fr/dashboard/session-security.mdx
@@ -10,24 +10,26 @@ keywords: ["session", "timeout", "authentication", "security", "SSO", "IP allowl
Les administrateurs Enterprise peuvent exiger que les utilisateurs du Dashboard se réauthentifient selon un calendrier adapté aux politiques de sécurité de votre organisation. Deux paramètres indépendants déterminent la fin d'une session du Dashboard :
-- **Durée d'inactivité de la session** : le temps pendant lequel une session peut rester inactive avant que l'utilisateur ne soit déconnecté.
+- **Délai d'inactivité de la session** : le temps pendant lequel une session peut rester inactive avant que l'utilisateur ne soit déconnecté.
- **Durée de vie maximale de la session** : la durée de vie absolue d'une session, indépendamment de l'activité. Une fois cette durée dépassée, l'utilisateur est déconnecté et doit se réauthentifier.
-Si un paramètre n'est pas configuré, la valeur par défaut de Mintlify s'applique. Les deux paramètres acceptent des valeurs comprises entre **5 minutes et 14 jours** (20 160 minutes).
+Chaque paramètre dispose de son propre interrupteur d'activation. Si un paramètre est désactivé, la valeur par défaut de Mintlify s'applique. Les deux paramètres acceptent des valeurs comprises entre **5 minutes et 14 jours** (20 160 minutes).
-
- ## Configurer la durée des sessions
+
+ ## Configurer les durées de session
-Pour consulter ou modifier les paramètres de sécurité des sessions, accédez à la page [Single Sign-On](https://app.mintlify.com/settings/organization/sso) de votre Dashboard.
+Pour consulter ou modifier les durées de session, accédez à l'onglet **Policies** de la page [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) de votre Dashboard.
-
- ### Durée d'inactivité de la session
+Pour chaque paramètre, utilisez l'interrupteur pour l'activer ou le désactiver, saisissez une valeur, choisissez une unité (minutes, heures, jours ou semaines pour la durée de vie maximale ; minutes, heures ou jours pour le délai d'inactivité), puis sélectionnez **Save**. Désactiver un paramètre et enregistrer efface sa valeur, de sorte que la valeur par défaut de Mintlify s'applique.
+
+
+ ### Délai d'inactivité de la session
-La durée d'inactivité de la session contrôle le temps pendant lequel une session peut rester inactive avant d'expirer. Toute requête envoyée par l'utilisateur au Dashboard réinitialise le compteur d'inactivité.
+Le délai d'inactivité de la session contrôle le temps pendant lequel une session peut rester inactive avant d'expirer. Toute requête envoyée par l'utilisateur au Dashboard réinitialise le compteur d'inactivité.
-Utilisez une durée d'inactivité plus courte pour réduire le risque que des sessions laissées sans surveillance soient utilisées par une personne autre que l'utilisateur connecté, par exemple sur des appareils partagés ou déverrouillés.
+Utilisez un délai d'inactivité plus court pour réduire le risque que des sessions laissées sans surveillance soient utilisées par une personne autre que l'utilisateur connecté, par exemple sur des appareils partagés ou déverrouillés.
### Durée de vie maximale de la session
@@ -43,10 +45,10 @@ Utilisez une durée de vie maximale pour garantir que les utilisateurs se réaut
Les deux paramètres s'appliquent indépendamment. La session d'un utilisateur prend fin à la première des deux limites atteintes :
-- Si l'utilisateur reste inactif plus longtemps que la **durée d'inactivité de la session**, la session prend fin.
+- Si l'utilisateur reste inactif plus longtemps que le **délai d'inactivité de la session**, la session prend fin.
- Si la **durée de vie maximale de la session** s'est écoulée depuis la connexion, la session prend fin même si l'utilisateur est actif.
-Par exemple, si vous définissez la durée d'inactivité sur 1 heure et la durée de vie maximale sur 8 heures, un utilisateur qui travaille activement est déconnecté au bout de 8 heures, et un utilisateur inactif est déconnecté au bout d'1 heure.
+Par exemple, si vous définissez le délai d'inactivité sur 1 heure et la durée de vie maximale sur 8 heures, un utilisateur qui travaille activement est déconnecté au bout de 8 heures, et un utilisateur inactif est déconnecté au bout d'1 heure.
## Restreindre l'accès au Dashboard par IP
@@ -58,13 +60,13 @@ Utilisez la liste d'autorisation d'adresses IP pour restreindre l'accès au Dash
Si votre adresse IP actuelle ne figure pas dans la liste d'autorisation, vous risquez de vous bloquer l'accès au Dashboard. Vérifiez que votre IP est incluse avant d'enregistrer.
-Pour configurer la liste d'autorisation, accédez à la page [Network access](https://app.mintlify.com/settings/organization/network-access) de votre Dashboard.
+Pour configurer la liste d'autorisation, accédez à l'onglet **Policies** de la page [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) de votre Dashboard.
- **Ajouter une entrée** : saisissez une adresse IPv4 ou IPv6, ou une plage CIDR (par exemple, `203.0.113.7` ou `10.0.0.0/8`), puis sélectionnez **Add**. L'ajout de la première entrée active la liste d'autorisation.
- **Supprimer une entrée** : sélectionnez le **×** sur n'importe quelle entrée. La suppression de la dernière entrée désactive la liste d'autorisation.
- **Vérifier votre IP** : votre adresse IP actuelle est affichée sous la liste des entrées afin que vous puissiez confirmer qu'elle est couverte avant d'enregistrer les modifications.
-Le badge d'état à côté de **Allowed IP addresses** affiche **Active** lorsqu'au moins une entrée est présente et **Disabled** lorsque la liste est vide.
+Le badge d'état à côté de **IP allowlist** affiche **Active** lorsqu'au moins une entrée est présente et **Disabled** lorsque la liste est vide.
## Journalisation d'audit
diff --git a/zh/dashboard/session-security.mdx b/zh/dashboard/session-security.mdx
index 51cd8a839a..fb6b2e8ee9 100644
--- a/zh/dashboard/session-security.mdx
+++ b/zh/dashboard/session-security.mdx
@@ -10,24 +10,26 @@ keywords: ["session", "timeout", "authentication", "security", "SSO", "IP allowl
Enterprise 管理员可以要求控制台用户按照符合组织安全策略的计划重新进行身份验证。有两个独立的控件决定控制台会话何时结束：
-- **空闲会话时长**：会话在用户被登出前可以保持不活动的时长。
+- **空闲会话超时**：会话在用户被登出前可以保持不活动的时长。
- **最大会话生命周期**：会话的绝对生命周期，与活动状态无关。超过该时长后，用户将被登出并必须重新进行身份验证。
-如果未配置某项设置，则应用 Mintlify 的默认值。两项设置均接受介于 **5 分钟到 14 天**（20,160 分钟）之间的值。
+每项设置都有各自的启用开关。如果某项设置被禁用，则应用 Mintlify 的默认值。两项设置均接受介于 **5 分钟到 14 天**（20,160 分钟）之间的值。
-
- ## 配置会话时长
+
+ ## 配置会话生命周期
-要查看或更改会话安全设置，请前往控制台的 [单点登录](https://app.mintlify.com/settings/organization/sso) 页面。
+要查看或更改会话生命周期，请前往控制台中 [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) 页面的 **Policies** 标签页。
-
- ### 空闲会话时长
+对于每项设置，使用开关启用或禁用它，输入一个值，选择一个单位（最大生命周期可选分钟、小时、天或周；空闲超时可选分钟、小时或天），然后选择 **Save**。禁用某项设置并保存会清除该设置，从而由 Mintlify 的默认值接管。
+
+
+ ### 空闲会话超时
-空闲会话时长控制会话在过期前可以保持不活动的时长。用户发出的任何控制台请求都会重置空闲计时器。
+空闲会话超时控制会话在过期前可以保持不活动的时长。用户发出的任何控制台请求都会重置空闲计时器。
-使用较短的空闲时长可以降低无人值守的会话被登录用户之外的其他人使用的风险，例如在共享或未锁定的设备上。
+使用较短的空闲超时可以降低无人值守的会话被登录用户之外的其他人使用的风险，例如在共享或未锁定的设备上。
### 最大会话生命周期
@@ -43,10 +45,10 @@ Enterprise 管理员可以要求控制台用户按照符合组织安全策略的
两项设置独立生效。用户的会话在任一限制先达到时结束：
-- 如果用户处于不活动状态超过 **空闲会话时长**，会话结束。
+- 如果用户处于不活动状态超过 **空闲会话超时**，会话结束。
- 如果自登录起已过 **最大会话生命周期**，即使用户处于活跃状态，会话也会结束。
-例如，如果你将空闲时长设为 1 小时，最大生命周期设为 8 小时，那么持续工作的用户在 8 小时后被登出，而空闲用户在 1 小时后被登出。
+例如，如果你将空闲会话超时设为 1 小时，最大生命周期设为 8 小时，那么持续工作的用户在 8 小时后被登出，而空闲用户在 1 小时后被登出。
## 通过 IP 限制控制台访问
@@ -58,13 +60,13 @@ Enterprise 管理员可以要求控制台用户按照符合组织安全策略的
如果你当前的 IP 地址不在允许列表中，你可能会将自己锁定在控制台之外。请在保存前确认你的 IP 已包含在内。
-要配置允许列表，请前往控制台的 [网络访问](https://app.mintlify.com/settings/organization/network-access) 页面。
+要配置允许列表，请前往控制台中 [Identity & access](https://app.mintlify.com/settings/organization/access?tab=policies) 页面的 **Policies** 标签页。
- **添加条目**：输入 IPv4 或 IPv6 地址，或 CIDR 范围（例如 `203.0.113.7` 或 `10.0.0.0/8`），然后选择 **Add**。添加第一个条目将启用允许列表。
- **移除条目**：选择任意条目上的 **×**。移除最后一个条目将停用允许列表。
- **检查你的 IP**：你当前的 IP 地址会显示在条目列表下方，便于你在保存更改前确认它已被覆盖。
-**Allowed IP addresses** 旁边的状态徽章在至少存在一个条目时显示为 **Active**，在列表为空时显示为 **Disabled**。
+**IP allowlist** 旁边的状态徽章在至少存在一个条目时显示为 **Active**，在列表为空时显示为 **Disabled**。
## 审计日志
From e8abc5d3f978bf047a8d04889de8f9c4142a04a5 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 28 Jul 2026 16:13:15 +0000
Subject: [PATCH 5/5] chore: merge main into PR branch and resolve docs.json
conflicts
---
.github/workflows/agent-context-ci.yml | 33 +
.github/workflows/check-links.yml | 4 +-
.github/workflows/sync-agent-context.yml | 132 ++++
.mintignore | 2 +
.../skills/custom-domain-rate-limit/skill.mdx | 18 +
.../assistant/skills/editor-reset/skill.mdx | 19 +
.../skills/git-revalidation/skill.mdx | 22 +
.../config/vocabularies/Mintlify/accept.txt | 87 ++-
admin-openapi.json | 149 ++++-
agent-context/.gitignore | 3 +
agent-context/LICENSE | 21 +
agent-context/README.md | 60 ++
agent-context/context/mcp-servers.json | 10 +
.../context/skills/mintlify/SKILL.md | 240 +++++++
.../skills/mintlify/reference/api-docs.md | 141 +++++
.../context/skills/mintlify/reference/cli.md | 67 ++
.../skills/mintlify/reference/components.md | 517 +++++++++++++++
.../mintlify/reference/configuration.md | 591 ++++++++++++++++++
.../skills/mintlify/reference/navigation.md | 352 +++++++++++
.../mintlify/reference/product-context.md | 53 ++
agent-context/package.json | 15 +
agent-context/scripts/build.mjs | 12 +
agent-context/scripts/check.mjs | 36 ++
agent-context/scripts/lib.mjs | 154 +++++
agent-context/scripts/status.mjs | 37 ++
agent-context/scripts/sync-target.mjs | 13 +
agent-context/targets/claude.json | 6 +
agent-context/targets/codex.json | 6 +
agent-context/targets/cursor.json | 6 +
agent-context/test/build.test.mjs | 84 +++
agent/customize.mdx | 4 +-
agent/index.mdx | 31 +-
agent/slack.mdx | 61 +-
agent/use-cases.mdx | 2 +-
ai-native.mdx | 2 +-
ai/contextual-menu.mdx | 23 +-
ai/llmstxt.mdx | 1 +
ai/markdown-export.mdx | 39 +-
ai/mintlify-mcp.mdx | 48 +-
ai/model-context-protocol.mdx | 4 +-
ai/skillmd.mdx | 37 +-
analytics.openapi.json | 16 +-
api-playground/adding-sdk-examples.mdx | 4 +-
api-playground/graphql-setup.mdx | 103 +++
api-playground/openapi-setup.mdx | 6 +-
api-playground/sdk-reference-setup.mdx | 117 ++++
api-playground/troubleshooting.mdx | 21 +-
api/admin/deslop.mdx | 32 +
api/assistant/get-page-content.mdx | 1 +
api/introduction.mdx | 23 +-
api/static-export/overview.mdx | 2 +-
assistant/customize.mdx | 4 +-
assistant/widget-preview.mdx | 11 +
assistant/widget.mdx | 260 ++++++++
automations/create.mdx | 2 +-
automations/index.mdx | 13 +-
automations/integrations.mdx | 174 ++++--
automations/manage.mdx | 9 +-
automations/reference.mdx | 30 +-
changelog.mdx | 163 ++++-
cli/commands.mdx | 152 ++++-
cli/index.mdx | 6 +
cli/install.mdx | 30 +
components/cards.mdx | 2 +-
components/icons.mdx | 10 +
components/tree.mdx | 32 +
components/update.mdx | 2 +-
contact-support.mdx | 5 +-
create/changelogs.mdx | 2 +
create/reusable-snippets.mdx | 90 ++-
create/text.mdx | 31 +-
credits.mdx | 4 +-
customize/custom-domain.mdx | 98 +--
customize/custom-scripts.mdx | 29 +-
dashboard/audit-logs.mdx | 72 ++-
dashboard/network-access.mdx | 55 ++
dashboard/roles.mdx | 44 +-
dashboard/scim.mdx | 95 +++
dashboard/sso.mdx | 62 +-
deploy/authentication-setup.mdx | 54 +-
deploy/ci.mdx | 32 +-
.../cloudflare-firewall-troubleshooting.mdx | 58 +-
deploy/cloudflare.mdx | 52 +-
deploy/custom-portal.mdx | 80 +++
deploy/docs-subpath.mdx | 22 +-
deploy/ghes.mdx | 2 +-
deploy/github.mdx | 32 +-
deploy/monorepo.mdx | 12 +-
deploy/multi-repo.mdx | 14 +-
deploy/preview-deployments.mdx | 6 +
deploy/reverse-proxy.mdx | 278 ++------
deploy/route53-cloudfront.mdx | 69 +-
deploy/self-host.mdx | 239 +++++++
deploy/vercel-external-proxies.mdx | 8 +-
deploy/vercel.mdx | 25 +-
discovery-openapi.json | 26 +-
docs.json | 187 +++---
editor/branching-and-publishing.mdx | 45 +-
editor/comments.mdx | 83 +++
editor/drafts.mdx | 97 +++
editor/index.mdx | 20 +
editor/keyboard-shortcuts.mdx | 2 +
editor/settings.mdx | 28 +-
editor/suggestions.mdx | 50 ++
enterprise-contracting.mdx | 2 +-
es.json | 185 +++---
es/admin-openapi.json | 149 ++++-
es/agent/index.mdx | 27 +-
es/agent/slack.mdx | 31 +-
es/agent/use-cases.mdx | 2 +-
es/ai-native.mdx | 2 +-
es/ai/contextual-menu.mdx | 25 +-
es/ai/llmstxt.mdx | 1 +
es/ai/markdown-export.mdx | 41 +-
es/ai/mintlify-mcp.mdx | 48 +-
es/ai/model-context-protocol.mdx | 6 +-
es/ai/skillmd.mdx | 37 +-
es/analytics.openapi.json | 8 +-
es/api-playground/graphql-setup.mdx | 113 ++++
es/api-playground/openapi-setup.mdx | 10 +-
es/api-playground/sdk-reference-setup.mdx | 128 ++++
es/api-playground/troubleshooting.mdx | 10 +-
es/api/admin/deslop.mdx | 38 ++
es/api/introduction.mdx | 10 +-
es/assistant/widget-preview.mdx | 11 +
es/assistant/widget.mdx | 292 +++++++++
es/automations/create.mdx | 2 +-
es/automations/index.mdx | 11 +-
es/automations/integrations.mdx | 179 +++---
es/automations/manage.mdx | 9 +-
es/automations/reference.mdx | 20 +-
es/changelog.mdx | 201 +++++-
es/cli/commands.mdx | 164 ++++-
es/cli/index.mdx | 12 +
es/cli/install.mdx | 30 +
es/components/cards.mdx | 2 +-
es/components/icons.mdx | 10 +
es/components/tree.mdx | 38 +-
es/components/update.mdx | 2 +-
es/contact-support.mdx | 5 +-
es/create/changelogs.mdx | 2 +
es/create/reusable-snippets.mdx | 37 +-
es/create/text.mdx | 33 +-
es/credits.mdx | 2 +-
es/customize/custom-domain.mdx | 148 +++--
es/customize/custom-scripts.mdx | 39 +-
es/dashboard/audit-logs.mdx | 88 ++-
es/dashboard/network-access.mdx | 63 ++
es/dashboard/roles.mdx | 106 +++-
es/dashboard/scim.mdx | 109 ++++
es/dashboard/sso.mdx | 148 +++--
es/deploy/authentication-setup.mdx | 56 +-
es/deploy/ci.mdx | 26 +-
.../cloudflare-firewall-troubleshooting.mdx | 2 +-
es/deploy/cloudflare.mdx | 93 +--
es/deploy/custom-portal.mdx | 90 +++
es/deploy/docs-subpath.mdx | 26 +-
es/deploy/github.mdx | 12 +-
es/deploy/gitlab.mdx | 8 +-
es/deploy/monorepo.mdx | 14 +-
es/deploy/multi-repo.mdx | 16 +-
es/deploy/preview-deployments.mdx | 8 +
es/deploy/reverse-proxy.mdx | 306 ++-------
es/deploy/route53-cloudfront.mdx | 64 +-
es/deploy/self-host.mdx | 261 ++++++++
es/deploy/vercel.mdx | 32 +-
es/discovery-openapi.json | 26 +-
es/editor/branching-and-publishing.mdx | 8 +-
es/editor/comments.mdx | 92 +++
es/editor/drafts.mdx | 111 ++++
es/editor/index.mdx | 24 +
es/editor/keyboard-shortcuts.mdx | 2 +
es/editor/settings.mdx | 59 +-
es/editor/suggestions.mdx | 55 ++
es/enterprise-contracting.mdx | 2 +-
es/guides/claude-code.mdx | 1 +
es/guides/codex.mdx | 6 +-
es/guides/custom-frontend.mdx | 4 +-
es/integrations/analytics/overview.mdx | 20 +-
es/migration-services/enterprise.mdx | 113 ++--
es/migration-services/go-live-checklist.mdx | 55 ++
es/migration-services/pro.mdx | 133 ----
es/openapi.json | 10 +-
es/optimize/analytics.mdx | 349 +++++++----
es/optimize/feedback.mdx | 161 +++--
es/optimize/search.mdx | 28 +-
es/optimize/seo.mdx | 52 ++
es/organize/navigation.mdx | 80 ++-
es/organize/pages.mdx | 10 +
es/organize/related-pages.mdx | 105 ++++
es/organize/settings-reference.mdx | 44 +-
es/organize/settings-seo.mdx | 24 +
es/quickstart.mdx | 2 +-
es/static-export-openapi.json | 10 +-
fr.json | 185 +++---
fr/admin-openapi.json | 149 ++++-
fr/agent/customize.mdx | 2 +-
fr/agent/index.mdx | 27 +-
fr/agent/slack.mdx | 31 +-
fr/agent/use-cases.mdx | 2 +-
fr/ai-native.mdx | 2 +-
fr/ai/contextual-menu.mdx | 25 +-
fr/ai/llmstxt.mdx | 1 +
fr/ai/markdown-export.mdx | 41 +-
fr/ai/mintlify-mcp.mdx | 48 +-
fr/ai/model-context-protocol.mdx | 6 +-
fr/ai/skillmd.mdx | 37 +-
fr/analytics.openapi.json | 8 +-
fr/api-playground/graphql-setup.mdx | 113 ++++
fr/api-playground/openapi-setup.mdx | 10 +-
fr/api-playground/sdk-reference-setup.mdx | 128 ++++
fr/api-playground/troubleshooting.mdx | 10 +-
fr/api/admin/deslop.mdx | 38 ++
fr/api/introduction.mdx | 10 +-
fr/assistant/widget-preview.mdx | 11 +
fr/assistant/widget.mdx | 292 +++++++++
fr/automations/create.mdx | 2 +-
fr/automations/index.mdx | 11 +-
fr/automations/integrations.mdx | 179 +++---
fr/automations/manage.mdx | 9 +-
fr/automations/reference.mdx | 20 +-
fr/changelog.mdx | 201 +++++-
fr/cli/commands.mdx | 166 ++++-
fr/cli/index.mdx | 12 +
fr/cli/install.mdx | 30 +
fr/components/cards.mdx | 2 +-
fr/components/icons.mdx | 10 +
fr/components/tree.mdx | 38 +-
fr/components/update.mdx | 2 +-
fr/contact-support.mdx | 5 +-
fr/create/changelogs.mdx | 2 +
fr/create/reusable-snippets.mdx | 37 +-
fr/create/text.mdx | 33 +-
fr/credits.mdx | 2 +-
fr/customize/custom-domain.mdx | 136 ++--
fr/customize/custom-scripts.mdx | 39 +-
fr/dashboard/audit-logs.mdx | 154 +++--
fr/dashboard/network-access.mdx | 63 ++
fr/dashboard/roles.mdx | 58 +-
fr/dashboard/scim.mdx | 109 ++++
fr/dashboard/sso.mdx | 172 +++--
fr/deploy/authentication-setup.mdx | 56 +-
fr/deploy/ci.mdx | 26 +-
.../cloudflare-firewall-troubleshooting.mdx | 2 +-
fr/deploy/cloudflare.mdx | 41 +-
fr/deploy/custom-portal.mdx | 90 +++
fr/deploy/docs-subpath.mdx | 26 +-
fr/deploy/github.mdx | 12 +-
fr/deploy/gitlab.mdx | 8 +-
fr/deploy/monorepo.mdx | 14 +-
fr/deploy/multi-repo.mdx | 16 +-
fr/deploy/preview-deployments.mdx | 8 +
fr/deploy/reverse-proxy.mdx | 310 ++-------
fr/deploy/route53-cloudfront.mdx | 65 +-
fr/deploy/self-host.mdx | 261 ++++++++
fr/deploy/vercel.mdx | 27 +-
fr/discovery-openapi.json | 26 +-
fr/editor/branching-and-publishing.mdx | 8 +-
fr/editor/comments.mdx | 92 +++
fr/editor/drafts.mdx | 111 ++++
fr/editor/index.mdx | 22 +
fr/editor/keyboard-shortcuts.mdx | 2 +
fr/editor/settings.mdx | 59 +-
fr/editor/suggestions.mdx | 55 ++
fr/enterprise-contracting.mdx | 2 +-
fr/guides/claude-code.mdx | 2 +
fr/guides/codex.mdx | 6 +-
fr/guides/custom-frontend.mdx | 4 +-
fr/integrations/analytics/overview.mdx | 20 +-
fr/migration-services/enterprise.mdx | 125 ++--
fr/migration-services/go-live-checklist.mdx | 55 ++
fr/migration-services/pro.mdx | 133 ----
fr/openapi.json | 10 +-
fr/optimize/analytics.mdx | 350 +++++++----
fr/optimize/feedback.mdx | 160 +++--
fr/optimize/search.mdx | 28 +-
fr/optimize/seo.mdx | 52 ++
fr/organize/navigation.mdx | 172 +++--
fr/organize/pages.mdx | 10 +
fr/organize/related-pages.mdx | 105 ++++
fr/organize/settings-reference.mdx | 44 +-
fr/organize/settings-seo.mdx | 24 +
fr/quickstart.mdx | 2 +-
fr/static-export-openapi.json | 10 +-
guides/claude-code.mdx | 10 +
guides/codex.mdx | 12 +-
images/agent/install-apps-dark.png | Bin 140961 -> 0 bytes
images/agent/install-apps-light.png | Bin 141151 -> 0 bytes
images/analytics/agent-feedback-dark.png | Bin 75134 -> 0 bytes
images/analytics/agent-feedback-light.png | Bin 74823 -> 0 bytes
images/analytics/assistant-dark.png | Bin 0 -> 245808 bytes
images/analytics/assistant-light.png | Bin 0 -> 244091 bytes
images/analytics/export-to-csv-dark.png | Bin 0 -> 30974 bytes
images/analytics/export-to-csv-light.png | Bin 0 -> 31411 bytes
images/analytics/feedback-dark.png | Bin 146225 -> 144704 bytes
images/analytics/feedback-light.png | Bin 145188 -> 144110 bytes
images/analytics/search-dark.png | Bin 0 -> 119399 bytes
images/analytics/search-light.png | Bin 0 -> 118166 bytes
images/analytics/traffic-dark.png | Bin 0 -> 254879 bytes
images/analytics/traffic-filter-dark.png | Bin 35466 -> 0 bytes
images/analytics/traffic-filter-light.png | Bin 35853 -> 0 bytes
images/analytics/traffic-light.png | Bin 0 -> 252278 bytes
images/domain/add-custom-domain-dark.png | Bin 103783 -> 0 bytes
images/domain/add-custom-domain-light.png | Bin 105737 -> 0 bytes
images/editor/comment-dark.png | Bin 145752 -> 134506 bytes
images/editor/comment-light.png | Bin 146427 -> 136908 bytes
images/editor/deployment-selector-dark.png | Bin 0 -> 24012 bytes
images/editor/deployment-selector-light.png | Bin 0 -> 23841 bytes
images/editor/suggesting-dark.png | Bin 188262 -> 84181 bytes
images/editor/suggesting-light.png | Bin 190857 -> 87381 bytes
images/logos/aws-mark.svg | 3 +
images/logos/azure.svg | 23 +
images/logos/gcp.svg | 1 +
images/logos/kubernetes.svg | 1 +
images/logos/openshift.svg | 1 +
images/logos/oracle-mark.svg | 1 +
images/subpath/toggle-dark.png | Bin 49876 -> 0 bytes
images/subpath/toggle-light.png | Bin 49263 -> 0 bytes
images/support-button.png | Bin 0 -> 327018 bytes
integrations/analytics/overview.mdx | 18 +-
integrations/sdks/speakeasy.mdx | 2 +-
migration-services/enterprise.mdx | 66 +-
migration-services/go-live-checklist.mdx | 45 ++
migration-services/pro.mdx | 123 ----
openapi.json | 10 +-
optimize/analytics.mdx | 293 ++++++---
optimize/feedback.mdx | 101 ++-
optimize/search.mdx | 26 +-
optimize/seo.mdx | 41 +-
organize/navigation.mdx | 153 +++--
organize/pages.mdx | 10 +
organize/related-pages.mdx | 84 +++
organize/settings-reference.mdx | 42 +-
organize/settings-seo.mdx | 24 +
playground.css | 56 ++
redirects.json | 48 +-
snippets/assistant-widget-playground.jsx | 550 ++++++++++++++++
snippets/assistant-widget-preview-host.jsx | 271 ++++++++
snippets/custom-subpath-propagating.mdx | 2 +-
snippets/es/custom-subpath-propagating.mdx | 4 +-
snippets/es/icons-required.mdx | 21 +-
snippets/es/subpath-setup-steps.mdx | 5 +
snippets/es/vercel-json-generator.mdx | 32 +-
snippets/fr/custom-subpath-propagating.mdx | 4 +-
snippets/fr/icons-required.mdx | 25 +-
snippets/fr/subpath-setup-steps.mdx | 5 +
snippets/fr/vercel-json-generator.mdx | 32 +-
snippets/icons-required.mdx | 20 +-
snippets/subpath-setup-steps.mdx | 5 +
snippets/vercel-json-generator.mdx | 30 +-
snippets/zh/custom-subpath-propagating.mdx | 4 +-
snippets/zh/icons-required.mdx | 21 +-
snippets/zh/subpath-setup-steps.mdx | 5 +
snippets/zh/vercel-json-generator.mdx | 32 +-
static-export-openapi.json | 10 +-
zh.json | 185 +++---
zh/admin-openapi.json | 149 ++++-
zh/agent/index.mdx | 27 +-
zh/agent/slack.mdx | 29 +-
zh/agent/use-cases.mdx | 2 +-
zh/ai-native.mdx | 2 +-
zh/ai/contextual-menu.mdx | 23 +-
zh/ai/llmstxt.mdx | 1 +
zh/ai/markdown-export.mdx | 41 +-
zh/ai/mintlify-mcp.mdx | 48 +-
zh/ai/model-context-protocol.mdx | 8 +-
zh/ai/skillmd.mdx | 37 +-
zh/analytics.openapi.json | 8 +-
zh/api-playground/graphql-setup.mdx | 113 ++++
zh/api-playground/openapi-setup.mdx | 10 +-
zh/api-playground/sdk-reference-setup.mdx | 128 ++++
zh/api-playground/troubleshooting.mdx | 10 +-
zh/api/admin/deslop.mdx | 38 ++
zh/api/introduction.mdx | 8 +-
zh/assistant/widget-preview.mdx | 11 +
zh/assistant/widget.mdx | 292 +++++++++
zh/automations/create.mdx | 2 +-
zh/automations/index.mdx | 11 +-
zh/automations/integrations.mdx | 179 +++---
zh/automations/manage.mdx | 9 +-
zh/automations/reference.mdx | 20 +-
zh/changelog.mdx | 201 +++++-
zh/cli/commands.mdx | 168 ++++-
zh/cli/index.mdx | 12 +
zh/cli/install.mdx | 30 +
zh/components/cards.mdx | 2 +-
zh/components/icons.mdx | 10 +
zh/components/tree.mdx | 38 +-
zh/components/update.mdx | 2 +-
zh/contact-support.mdx | 5 +-
zh/create/changelogs.mdx | 2 +
zh/create/reusable-snippets.mdx | 37 +-
zh/create/text.mdx | 33 +-
zh/credits.mdx | 2 +-
zh/customize/custom-domain.mdx | 156 +++--
zh/customize/custom-scripts.mdx | 39 +-
zh/dashboard/audit-logs.mdx | 104 ++-
zh/dashboard/network-access.mdx | 63 ++
zh/dashboard/roles.mdx | 106 +++-
zh/dashboard/scim.mdx | 109 ++++
zh/dashboard/sso.mdx | 168 +++--
zh/deploy/authentication-setup.mdx | 54 +-
zh/deploy/ci.mdx | 26 +-
.../cloudflare-firewall-troubleshooting.mdx | 2 +-
zh/deploy/cloudflare.mdx | 39 +-
zh/deploy/custom-portal.mdx | 90 +++
zh/deploy/docs-subpath.mdx | 28 +-
zh/deploy/github.mdx | 12 +-
zh/deploy/gitlab.mdx | 10 +-
zh/deploy/monorepo.mdx | 14 +-
zh/deploy/multi-repo.mdx | 16 +-
zh/deploy/preview-deployments.mdx | 8 +
zh/deploy/reverse-proxy.mdx | 300 ++-------
zh/deploy/route53-cloudfront.mdx | 65 +-
zh/deploy/self-host.mdx | 261 ++++++++
zh/deploy/vercel.mdx | 27 +-
zh/discovery-openapi.json | 26 +-
zh/editor/branching-and-publishing.mdx | 8 +-
zh/editor/comments.mdx | 92 +++
zh/editor/drafts.mdx | 111 ++++
zh/editor/index.mdx | 22 +
zh/editor/keyboard-shortcuts.mdx | 2 +
zh/editor/settings.mdx | 53 +-
zh/editor/suggestions.mdx | 55 ++
zh/guides/claude-code.mdx | 1 +
zh/guides/codex.mdx | 6 +-
zh/guides/custom-frontend.mdx | 4 +-
zh/integrations/analytics/overview.mdx | 20 +-
zh/migration-services/enterprise.mdx | 119 ++--
zh/migration-services/go-live-checklist.mdx | 55 ++
zh/migration-services/pro.mdx | 133 ----
zh/openapi.json | 10 +-
zh/optimize/analytics.mdx | 349 +++++++----
zh/optimize/feedback.mdx | 166 +++--
zh/optimize/search.mdx | 28 +-
zh/optimize/seo.mdx | 52 ++
zh/organize/navigation.mdx | 84 ++-
zh/organize/pages.mdx | 10 +
zh/organize/related-pages.mdx | 105 ++++
zh/organize/settings-reference.mdx | 40 +-
zh/organize/settings-seo.mdx | 24 +
zh/quickstart.mdx | 2 +-
zh/static-export-openapi.json | 10 +-
443 files changed, 19427 insertions(+), 5092 deletions(-)
create mode 100644 .github/workflows/agent-context-ci.yml
create mode 100644 .github/workflows/sync-agent-context.yml
create mode 100644 .mintignore
create mode 100644 .mintlify/assistant/skills/custom-domain-rate-limit/skill.mdx
create mode 100644 .mintlify/assistant/skills/editor-reset/skill.mdx
create mode 100644 .mintlify/assistant/skills/git-revalidation/skill.mdx
create mode 100644 agent-context/.gitignore
create mode 100644 agent-context/LICENSE
create mode 100644 agent-context/README.md
create mode 100644 agent-context/context/mcp-servers.json
create mode 100644 agent-context/context/skills/mintlify/SKILL.md
create mode 100644 agent-context/context/skills/mintlify/reference/api-docs.md
create mode 100644 agent-context/context/skills/mintlify/reference/cli.md
create mode 100644 agent-context/context/skills/mintlify/reference/components.md
create mode 100644 agent-context/context/skills/mintlify/reference/configuration.md
create mode 100644 agent-context/context/skills/mintlify/reference/navigation.md
create mode 100644 agent-context/context/skills/mintlify/reference/product-context.md
create mode 100644 agent-context/package.json
create mode 100644 agent-context/scripts/build.mjs
create mode 100644 agent-context/scripts/check.mjs
create mode 100644 agent-context/scripts/lib.mjs
create mode 100644 agent-context/scripts/status.mjs
create mode 100644 agent-context/scripts/sync-target.mjs
create mode 100644 agent-context/targets/claude.json
create mode 100644 agent-context/targets/codex.json
create mode 100644 agent-context/targets/cursor.json
create mode 100644 agent-context/test/build.test.mjs
create mode 100644 api-playground/graphql-setup.mdx
create mode 100644 api-playground/sdk-reference-setup.mdx
create mode 100644 api/admin/deslop.mdx
create mode 100644 assistant/widget-preview.mdx
create mode 100644 assistant/widget.mdx
create mode 100644 dashboard/network-access.mdx
create mode 100644 dashboard/scim.mdx
create mode 100644 deploy/custom-portal.mdx
create mode 100644 deploy/self-host.mdx
create mode 100644 editor/comments.mdx
create mode 100644 editor/drafts.mdx
create mode 100644 editor/suggestions.mdx
create mode 100644 es/api-playground/graphql-setup.mdx
create mode 100644 es/api-playground/sdk-reference-setup.mdx
create mode 100644 es/api/admin/deslop.mdx
create mode 100644 es/assistant/widget-preview.mdx
create mode 100644 es/assistant/widget.mdx
create mode 100644 es/dashboard/network-access.mdx
create mode 100644 es/dashboard/scim.mdx
create mode 100644 es/deploy/custom-portal.mdx
create mode 100644 es/deploy/self-host.mdx
create mode 100644 es/editor/comments.mdx
create mode 100644 es/editor/drafts.mdx
create mode 100644 es/editor/suggestions.mdx
create mode 100644 es/migration-services/go-live-checklist.mdx
delete mode 100644 es/migration-services/pro.mdx
create mode 100644 es/organize/related-pages.mdx
create mode 100644 fr/api-playground/graphql-setup.mdx
create mode 100644 fr/api-playground/sdk-reference-setup.mdx
create mode 100644 fr/api/admin/deslop.mdx
create mode 100644 fr/assistant/widget-preview.mdx
create mode 100644 fr/assistant/widget.mdx
create mode 100644 fr/dashboard/network-access.mdx
create mode 100644 fr/dashboard/scim.mdx
create mode 100644 fr/deploy/custom-portal.mdx
create mode 100644 fr/deploy/self-host.mdx
create mode 100644 fr/editor/comments.mdx
create mode 100644 fr/editor/drafts.mdx
create mode 100644 fr/editor/suggestions.mdx
create mode 100644 fr/migration-services/go-live-checklist.mdx
delete mode 100644 fr/migration-services/pro.mdx
create mode 100644 fr/organize/related-pages.mdx
delete mode 100644 images/agent/install-apps-dark.png
delete mode 100644 images/agent/install-apps-light.png
delete mode 100644 images/analytics/agent-feedback-dark.png
delete mode 100644 images/analytics/agent-feedback-light.png
create mode 100644 images/analytics/assistant-dark.png
create mode 100644 images/analytics/assistant-light.png
create mode 100644 images/analytics/export-to-csv-dark.png
create mode 100644 images/analytics/export-to-csv-light.png
create mode 100644 images/analytics/search-dark.png
create mode 100644 images/analytics/search-light.png
create mode 100644 images/analytics/traffic-dark.png
delete mode 100644 images/analytics/traffic-filter-dark.png
delete mode 100644 images/analytics/traffic-filter-light.png
create mode 100644 images/analytics/traffic-light.png
delete mode 100644 images/domain/add-custom-domain-dark.png
delete mode 100644 images/domain/add-custom-domain-light.png
create mode 100644 images/editor/deployment-selector-dark.png
create mode 100644 images/editor/deployment-selector-light.png
create mode 100644 images/logos/aws-mark.svg
create mode 100644 images/logos/azure.svg
create mode 100644 images/logos/gcp.svg
create mode 100644 images/logos/kubernetes.svg
create mode 100644 images/logos/openshift.svg
create mode 100644 images/logos/oracle-mark.svg
delete mode 100644 images/subpath/toggle-dark.png
delete mode 100644 images/subpath/toggle-light.png
create mode 100644 images/support-button.png
create mode 100644 migration-services/go-live-checklist.mdx
delete mode 100644 migration-services/pro.mdx
create mode 100644 organize/related-pages.mdx
create mode 100644 playground.css
create mode 100644 snippets/assistant-widget-playground.jsx
create mode 100644 snippets/assistant-widget-preview-host.jsx
create mode 100644 snippets/es/subpath-setup-steps.mdx
create mode 100644 snippets/fr/subpath-setup-steps.mdx
create mode 100644 snippets/subpath-setup-steps.mdx
create mode 100644 snippets/zh/subpath-setup-steps.mdx
create mode 100644 zh/api-playground/graphql-setup.mdx
create mode 100644 zh/api-playground/sdk-reference-setup.mdx
create mode 100644 zh/api/admin/deslop.mdx
create mode 100644 zh/assistant/widget-preview.mdx
create mode 100644 zh/assistant/widget.mdx
create mode 100644 zh/dashboard/network-access.mdx
create mode 100644 zh/dashboard/scim.mdx
create mode 100644 zh/deploy/custom-portal.mdx
create mode 100644 zh/deploy/self-host.mdx
create mode 100644 zh/editor/comments.mdx
create mode 100644 zh/editor/drafts.mdx
create mode 100644 zh/editor/suggestions.mdx
create mode 100644 zh/migration-services/go-live-checklist.mdx
delete mode 100644 zh/migration-services/pro.mdx
create mode 100644 zh/organize/related-pages.mdx
diff --git a/.github/workflows/agent-context-ci.yml b/.github/workflows/agent-context-ci.yml
new file mode 100644
index 0000000000..76baca8270
--- /dev/null
+++ b/.github/workflows/agent-context-ci.yml
@@ -0,0 +1,33 @@
+name: Validate agent context
+
+on:
+ pull_request:
+ paths:
+ - agent-context/**
+ - .github/workflows/agent-context-ci.yml
+ - .github/workflows/sync-agent-context.yml
+ push:
+ branches: [main]
+ paths:
+ - agent-context/**
+ - .github/workflows/agent-context-ci.yml
+ - .github/workflows/sync-agent-context.yml
+
+permissions:
+ contents: read
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v6
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 24
+ package-manager-cache: false
+ - run: npm test
+ working-directory: agent-context
+ - run: npm run check
+ working-directory: agent-context
+ - run: npm run build
+ working-directory: agent-context
diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml
index 4d79515dcc..e86b90d1cd 100644
--- a/.github/workflows/check-links.yml
+++ b/.github/workflows/check-links.yml
@@ -7,9 +7,9 @@ jobs:
name: Check links
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v5
- name: Set up Node
- uses: actions/setup-node@v4
+ uses: actions/setup-node@v5
with:
node-version: "22.x"
- name: Install Mintlify CLI
diff --git a/.github/workflows/sync-agent-context.yml b/.github/workflows/sync-agent-context.yml
new file mode 100644
index 0000000000..790e258002
--- /dev/null
+++ b/.github/workflows/sync-agent-context.yml
@@ -0,0 +1,132 @@
+name: Sync plugin context
+
+on:
+ workflow_dispatch:
+ push:
+ branches: [main]
+ paths:
+ - agent-context/context/**
+ - agent-context/targets/**
+ - agent-context/scripts/**
+ - agent-context/test/**
+ - agent-context/package.json
+ - .github/workflows/sync-agent-context.yml
+
+permissions:
+ contents: read
+
+concurrency:
+ group: sync-plugin-context
+ cancel-in-progress: false
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v6
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 24
+ package-manager-cache: false
+ - run: npm test
+ working-directory: agent-context
+ - run: npm run check
+ working-directory: agent-context
+
+ sync:
+ needs: validate
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - target: codex
+ repository: mintlify/codex-plugin
+ repository_name: codex-plugin
+ mcp_file: .mcp.json
+ - target: cursor
+ repository: mintlify/cursor-plugin
+ repository_name: cursor-plugin
+ mcp_file: mcp.json
+ - target: claude
+ repository: mintlify/mintlify-claude-plugin
+ repository_name: mintlify-claude-plugin
+ mcp_file: .mcp.json
+
+ steps:
+ - name: Check out context source
+ uses: actions/checkout@v6
+ with:
+ path: source
+
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 24
+ package-manager-cache: false
+
+ - name: Create target repository token
+ id: app-token
+ uses: actions/create-github-app-token@v3
+ with:
+ client-id: ${{ vars.CONTEXT_SYNC_APP_CLIENT_ID }}
+ private-key: ${{ secrets.CONTEXT_SYNC_APP_PRIVATE_KEY }}
+ owner: mintlify
+ repositories: ${{ matrix.repository_name }}
+ permission-contents: write
+ permission-pull-requests: write
+
+ - name: Check out target repository
+ uses: actions/checkout@v6
+ with:
+ repository: ${{ matrix.repository }}
+ token: ${{ steps.app-token.outputs.token }}
+ path: target
+
+ - name: Generate target context
+ run: node source/agent-context/scripts/sync-target.mjs "${{ matrix.target }}" target
+
+ - name: Detect changes
+ id: changes
+ working-directory: target
+ run: |
+ if [[ -n "$(git status --porcelain)" ]]; then
+ echo "changed=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "changed=false" >> "$GITHUB_OUTPUT"
+ fi
+
+ - name: Commit and push sync branch
+ if: steps.changes.outputs.changed == 'true'
+ working-directory: target
+ env:
+ APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+ BRANCH: automation/sync-agent-context
+ run: |
+ git config user.name "${APP_SLUG}[bot]"
+ git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"
+ git checkout -B "$BRANCH"
+ git add skills/mintlify .mintlify-agent-context.json "${{ matrix.mcp_file }}"
+ git commit -m "Sync Mintlify agent context"
+ git fetch origin "$BRANCH:refs/remotes/origin/$BRANCH" || true
+ git push --force-with-lease origin "HEAD:$BRANCH"
+
+ - name: Open sync pull request
+ if: steps.changes.outputs.changed == 'true'
+ working-directory: target
+ env:
+ GH_TOKEN: ${{ steps.app-token.outputs.token }}
+ GH_REPO: ${{ matrix.repository }}
+ BRANCH: automation/sync-agent-context
+ SOURCE_SHA: ${{ github.sha }}
+ run: |
+ BODY="Generated from mintlify/docs at ${SOURCE_SHA} using agent-context. Do not edit generated skill files in this repository."
+ EXISTING_PR="$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number')"
+ if [[ -z "$EXISTING_PR" ]]; then
+ gh pr create \
+ --head "$BRANCH" \
+ --base main \
+ --title "Sync Mintlify agent context" \
+ --body "$BODY"
+ else
+ gh pr edit "$EXISTING_PR" --body "$BODY"
+ fi
diff --git a/.mintignore b/.mintignore
new file mode 100644
index 0000000000..9f4349f4bf
--- /dev/null
+++ b/.mintignore
@@ -0,0 +1,2 @@
+# Internal tooling that compiles context for external agent plugins.
+agent-context/
diff --git a/.mintlify/assistant/skills/custom-domain-rate-limit/skill.mdx b/.mintlify/assistant/skills/custom-domain-rate-limit/skill.mdx
new file mode 100644
index 0000000000..ea0246620b
--- /dev/null
+++ b/.mintlify/assistant/skills/custom-domain-rate-limit/skill.mdx
@@ -0,0 +1,18 @@
+---
+name: "custom-domain-rate-limit"
+description: "Use this skill when a user is setting up a custom domain and the _acme-challenge TXT record value never appears in the Mintlify dashboard — the dashboard shows a loading spinner, a blank field, or the value keeps changing on each attempt. This is caused by a Let's Encrypt certificate issuance rate limit from repeated failed validation attempts."
+---
+
+# Custom domain _acme-challenge value not appearing
+
+When the `_acme-challenge` TXT record value never loads in the dashboard, the cause is almost always a Let's Encrypt rate limit. Let's Encrypt limits how many certificate requests can be made for the same domain in a short window. Deleting and re-adding the domain, or retrying a failed validation, counts as a new attempt. After several failed attempts, Let's Encrypt imposes a cooldown before a new challenge token can be generated.
+
+Tell the user to:
+
+1. Wait 24-72 hours before retrying. The rate limit clears on its own.
+2. Leave the domain entry as-is in the dashboard. Deleting and re-adding the domain triggers new certificate requests and can extend the wait.
+3. Avoid refreshing or clicking retry. Additional attempts may extend the cooldown further.
+
+Once the cooldown clears, the `_acme-challenge` TXT value appears automatically. The user can then add it to their DNS and complete validation as normal.
+
+If the user has already been retrying repeatedly, the cooldown can extend up to 7 days. The best path forward is still to leave the domain entry in place and wait. If the value hasn't appeared after a week, direct the user to contact support.
diff --git a/.mintlify/assistant/skills/editor-reset/skill.mdx b/.mintlify/assistant/skills/editor-reset/skill.mdx
new file mode 100644
index 0000000000..de44f1cbf0
--- /dev/null
+++ b/.mintlify/assistant/skills/editor-reset/skill.mdx
@@ -0,0 +1,19 @@
+---
+name: "editor-reset"
+description: "Use this skill when a user reports that the Mintlify web editor is broken, not loading properly, showing outdated or stale content, or is stuck after a GitHub sync. Also applies when the file tree fails to load or the editor appears frozen or unresponsive."
+---
+
+# Reset the editor
+
+A force reset usually fixes a web editor that is broken, showing stale content, or failing to load the file tree — especially after a Git sync. Resetting clears local editor state without affecting published docs or Git history.
+
+Walk the user through these steps:
+
+1. Open the web editor at [app.mintlify.com](https://app.mintlify.com).
+2. Click the settings button in the editor toolbar. It has a gear icon and no text label.
+3. Scroll down to the **Reset Editor** section.
+4. Click **Reset Editor**.
+
+The editor reloads and re-syncs from the Git repository.
+
+If the issue persists after resetting, it may indicate a deeper sync conflict — escalate to the support team.
diff --git a/.mintlify/assistant/skills/git-revalidation/skill.mdx b/.mintlify/assistant/skills/git-revalidation/skill.mdx
new file mode 100644
index 0000000000..8eb0ce04ec
--- /dev/null
+++ b/.mintlify/assistant/skills/git-revalidation/skill.mdx
@@ -0,0 +1,22 @@
+---
+name: "git-revalidation"
+description: "Use this skill when a user reports that GitHub-dependent features have stopped working after they changed their repository from private to public or vice versa — Suggest Edits isn't showing on their docs, PR previews aren't generating, or branch options appear stale. Also applies when the Git connection appears stale or broken."
+---
+
+# Revalidate the Git connection
+
+When a repository's visibility changes (private to public or public to private), Mintlify's cached understanding of the repo's permissions becomes outdated. Features that depend on the GitHub connection — Suggest Edits, PR previews, branch syncing — can appear broken until the cache catches up to the new visibility state.
+
+Before recommending revalidation, check which direction the visibility changed:
+
+- **Private to public**: revalidation restores affected features, including Suggest Edits.
+- **Public to private**: Suggest Edits is only available for public GitHub repositories, so it is expected to disappear and revalidation will not restore it. Revalidation still fixes other stale-connection symptoms like PR previews or branch options.
+
+Walk the user through these steps:
+
+1. Go to the [Git Settings page](https://app.mintlify.com/settings/deployment/git-settings).
+2. Press `Cmd + Shift + Enter` (Mac) or `Ctrl + Shift + Enter` (Windows).
+
+This keyboard shortcut revalidates the Git connection. Mintlify re-checks the repository's visibility and permissions, which restores affected features.
+
+After revalidating, the user should allow a minute for changes to propagate, then refresh their docs site.
diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt
index 9ba1435a81..7c2c49c4af 100644
--- a/.vale/styles/config/vocabularies/Mintlify/accept.txt
+++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt
@@ -6,6 +6,7 @@ AEO
agentic
Ahrefs
AI
+AKS
allOf
allowlists?
AllViewerExceptHostHeader
@@ -22,10 +23,14 @@ api-server
api\.url
appId
ARIA
+ASCII
Astro
AsyncAPI
+Atlassian
(?i)auth
Auth0
+autocommit
+autofocuses
(?i)autogenerat(e|ed|ing)?
(?i)automations?
(?i)automerge
@@ -42,6 +47,8 @@ blockIgnores
boolean
borderRadius
(?i)breakglass
+bugfixes
+bundleUrl
CAA
CachingDisabled
CachingEnabled
@@ -52,11 +59,15 @@ camelCase
(?i)captchas?
Cascade
CD
+CDK
CDN
+chatbot
ChatGPT
Chromium
CI
+CIDR
CircleCI
+classnames
Claude
CLAUDE\.md
Claude's
@@ -66,6 +77,7 @@ CloudConvert
Cloudflare
CloudFront
Cloudinary
+Contentful
(?i)cmd
CNAME
CodeBlock
@@ -75,10 +87,12 @@ codeSamples
Codex
codex/AGENTS\.md
Cognition
+commenters
Composable
Composio
config
const
+cooldown
(?i)crawlable
CRMs
(?i)cron
@@ -93,25 +107,37 @@ Ctrl
cURL
(?i)cursor
Datadog
+debounced
+deduplication
+deprovision(s|ed|ing)?
(?i)dev
Devin
DevTools
Di(?:á|a)taxis
Discord
+doclet(s)?
discoverability
+dismissibility
Django
DMs?
DNS
DNSChecker
+DNSimple
docs\.json
+DocFX
+documentationUrl
+DocumentDB
Docusaurus
DOCX
+DOM
DORA
(?i)drilldown
DRY
DynamoDB
EasyList
+ECS
EdDSA
+ElastiCache
Elasticsearch
ELK
Entra
@@ -121,8 +147,11 @@ example\.com/api
(?i)expandables
Express
FAQs?
+Fathom
+Figma
(?i)favicons?
(?i)frontmatter
+fullscreen
FullStory
Gantt
GCP
@@ -136,6 +165,7 @@ GitBook
(?i)git (clone|pull|add|commit|push|checkout|status)
GitHub
GitLab
+GKE
Golang
GraphQL
Grok
@@ -147,6 +177,7 @@ hardcod(e[ds]?|ing)
hCaptcha
hcaptcha\.com
(?i)heatmaps?
+Helm
Heroku
Hightouch
hostname
@@ -164,6 +195,7 @@ Imgix
indexable
ingestible
IntelliJ
+Inter
Intercom
internal_id
iOS
@@ -171,6 +203,7 @@ IP
isHidden
ISO
Java
+Javadoc
JavaScript
JetBrains
Jira
@@ -184,6 +217,7 @@ JSON-LD
JSX
JWTs?
KaTeX
+Keycloak
Kotlin
kubeconfig
Kubernetes
@@ -200,27 +234,35 @@ Lua
lodash
Lucide
(?i)luma
+M2M
macOS
+ManagedReference
Markdown
+Maven
(?i)mcp
md
MDX
measurementId
(?i)memoiz(e[ds]?|ation)
+Memorystore
Mermaid
(?i)metatags?
+middleware
minimap
(?i)mintlify
misconfiguration
+misparse
(?i)Mixpanel
Mocha
mockups
MongoDB
(?i)monorepo
+mov
Multiline
myName
myObject
MySQL
+namespaced
namespaces?
Nango
(?i)navbar
@@ -231,33 +273,46 @@ Node.js
Notion
npm
npx
+nullable
Nuxt
NVDA
OAS
OAuth
+OCI
+Octokit
OG
OIDC
+OKE
(?i)oklch
Okta
+offboarding
+onboarded
onboarding
oneOf
openable
OpenAI
OpenAI's
(?i)openapi
+OpenShift
org
(?i)Osano
(?i)outdent
outsized
+overscroll
PageSpeed
pageUrl
+pageviews
Pandoc
+parallelization
ParamField
PDF
PDFs
PHP
+phpDocumentor
PII
+pipeable
Pirsch
+Porkbun
Playfair
PNG
pnpm
@@ -282,17 +337,21 @@ queryCategory
(?i)quickstarts?
RAG
RBAC
+RDS
React
ReadMe
Readybot
(?i)rebase
rebranded
Redis
+redoable
repos?
RequestExample
resolutionStatus
ResponseExample
ResponseField
+resync
+revalidat(e|es|ed|ing|ion)?
reupload(s|ed|ing)?
(?i)rgba?
ROI
@@ -307,21 +366,29 @@ SaaS
Salesforce
SAML
sandboxed
+sanitization
Scala
scannability
+SCIM
(?i)scrollable
+scrollbar
SDK
SDKs
SendSafely
SEO
Sequoia
+serverless
sessionRecording
Shiki
+signup
siteId
SLA
Slack
slugified
+slugging
+snake_case
SOC
+sourcemaps
Speakeasy
Splunk
Spring
@@ -336,7 +403,7 @@ Storybook
stringif(y|ied|ies|ying)
stylesPath
(?i)subcommands?
-subpaths?
+[Ss]ubpaths?
subschema
(?i)subscribable
(?i)substring
@@ -347,43 +414,57 @@ Swift
Tabler
Tailwind
targetable
+templated
TensorFlow
Terraform
TextMate
timeframe
TLS
tokenIgnores
+tokenization
TOML
(?i)tooltips?
topbar
+transpilation
TrueType
TSV
TTF
TTL
+Turnstile
Twoslash
(?i)txt
TypeDoc
TypeScript
UI
UIs
+uncached
(?i)uncheck(s|ed|ing)?
+undoable
ungroup(s|ed|ing)?
Unicode
Unix
unmerged
+untracked
+Unversioned
(?i)uris?
URL
URLs
useChat
UTC
UTF
+util
UX
+vCPU
(?i)vercel
vercel\.json
+viewport
+virtualized
(?i)vite
VoiceOver
+VPC
VPN
VS Code
+VSCode
Vue
Vuex
W3C
@@ -394,6 +475,7 @@ WAVE
WCAG
WebAIM
Webflow
+Webflow's
WebKit
WebM
WebP
@@ -405,8 +487,11 @@ Windsurf's
WOFF2?
[\w-]*openapi\.json
writeKey
+X-Forwarded-Proto
X-Llms-Txt
XML
XSS
+YouTube
YYYY
Zapier
+Zendesk
diff --git a/admin-openapi.json b/admin-openapi.json
index c433d51487..35b8d15754 100644
--- a/admin-openapi.json
+++ b/admin-openapi.json
@@ -16,11 +16,89 @@
}
],
"paths": {
+ "/v1/deslop/{projectId}": {
+ "post": {
+ "summary": "Detect AI-sounding prose in a page",
+ "description": "Analyzes a page for AI-generated prose and returns flagged passages with suggested rewrites. Consumes one AI credit per checked page. Skips pages under 50 words. Limited to 30 requests per minute per client IP address.",
+ "parameters": [
+ {
+ "name": "projectId",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" },
+ "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard."
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": ["path", "content"],
+ "properties": {
+ "path": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Repo-relative path of the page, used for reporting only."
+ },
+ "content": {
+ "type": "string",
+ "maxLength": 1000000,
+ "description": "The raw MDX or Markdown content of the page to check."
+ }
+ }
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The page was checked, or skipped because it was too short.",
+ "content": {
+ "application/json": { "schema": { "$ref": "#/components/schemas/DeslopResult" } }
+ }
+ },
+ "400": {
+ "description": "Invalid request body.",
+ "content": {
+ "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
+ }
+ },
+ "402": {
+ "description": "Insufficient AI credits.",
+ "content": {
+ "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
+ }
+ },
+ "429": {
+ "description": "Rate limit exceeded.",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string",
+ "example": "Too many requests, please try again later."
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "Detection is temporarily unavailable. No credit is charged.",
+ "content": {
+ "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
+ }
+ },
+ "500": {
+ "description": "An unexpected error occurred while processing the page."
+ }
+ }
+ }
+ },
"/v1/agent/{projectId}/job": {
"post": {
"summary": "Create agent job (v1)",
"deprecated": true,
- "description": "Deprecated: use [v2 create agent job](/api/agent/v2/create-agent-job) instead. Creates a new agent job that can generate and edit documentation based on provided messages and branch information.",
+ "description": "Deprecated: use [v2 create agent job](/api/agent/v2/create-agent-job) instead. Creates a new agent job that can generate and edit documentation based on provided messages and branch information.\n\nAuthenticate with an admin API key.",
"parameters": [
{
"name": "projectId",
@@ -117,7 +195,7 @@
"get": {
"summary": "Get agent job by ID (v1)",
"deprecated": true,
- "description": "Deprecated: use [v2 get agent job](/api/agent/v2/get-agent-job) instead. Retrieves the details and status of a specific agent job by its ID.",
+ "description": "Deprecated: use [v2 get agent job](/api/agent/v2/get-agent-job) instead. Retrieves the details and status of a specific agent job by its ID.\n\nAuthenticate with an admin API key.",
"parameters": [
{
"name": "projectId",
@@ -228,7 +306,7 @@
"get": {
"summary": "Get all agent jobs (v1)",
"deprecated": true,
- "description": "Deprecated: use [v2 get agent job](/api/agent/v2/get-agent-job) instead. Retrieves all agent jobs for the specified domain, including their status and details.",
+ "description": "Deprecated: use [v2 get agent job](/api/agent/v2/get-agent-job) instead. Retrieves all agent jobs for the specified domain, including their status and details.\n\nAuthenticate with an admin API key.",
"parameters": [
{
"name": "projectId",
@@ -361,7 +439,7 @@
"/v2/agent/{projectId}/job": {
"post": {
"summary": "Create agent job",
- "description": "Creates a new agent job that runs in the background. The job processes the prompt asynchronously — poll the get job endpoint to track progress. If the agent edits files successfully, a pull request is automatically created.",
+ "description": "Creates a new agent job that runs in the background. The job processes the prompt asynchronously — poll the get job endpoint to track progress. If the agent edits files successfully, a pull request is automatically created.\n\nAuthenticate with an admin API key.",
"parameters": [
{
"name": "projectId",
@@ -428,7 +506,7 @@
"/v2/agent/{projectId}/job/{id}": {
"get": {
"summary": "Get agent job",
- "description": "Retrieves the current status and details of an agent job. Poll this endpoint to track job progress.",
+ "description": "Retrieves the current status and details of an agent job. Poll this endpoint to track job progress.\n\nAuthenticate with an admin API key.",
"parameters": [
{
"name": "projectId",
@@ -476,7 +554,7 @@
"/v2/agent/{projectId}/job/{id}/message": {
"post": {
"summary": "Send follow-up message",
- "description": "Sends a follow-up message to an existing agent job. The message is processed asynchronously — poll the get job endpoint to track progress.",
+ "description": "Sends a follow-up message to an existing agent job. The message is processed asynchronously — poll the get job endpoint to track progress.\n\nAuthenticate with an admin API key.",
"parameters": [
{
"name": "projectId",
@@ -562,6 +640,63 @@
},
"components": {
"schemas": {
+ "DeslopResult": {
+ "type": "object",
+ "required": ["path", "skipped", "creditsCharged"],
+ "properties": {
+ "path": { "type": "string", "description": "The path from the request." },
+ "skipped": {
+ "type": "string",
+ "nullable": true,
+ "enum": ["too_short", null],
+ "description": "Reason the page was skipped, or null when the page was checked. `too_short` means the page had fewer than 50 words of prose and was not charged."
+ },
+ "predictionShort": {
+ "type": "string",
+ "enum": ["AI", "AI-Assisted", "Human", "Mixed"],
+ "description": "Overall verdict for the page. Present only when the page was checked."
+ },
+ "fractionAi": { "type": "number", "description": "Fraction of the page detected as AI-generated (0-1)." },
+ "fractionAiAssisted": { "type": "number", "description": "Fraction detected as AI-assisted (0-1)." },
+ "fractionHuman": { "type": "number", "description": "Fraction detected as human-written (0-1)." },
+ "windows": {
+ "type": "array",
+ "description": "Flagged (non-human) passages. Present only when the page was checked.",
+ "items": { "$ref": "#/components/schemas/DeslopWindow" }
+ },
+ "creditsCharged": { "type": "integer", "description": "AI credits charged for this request (0 when skipped)." }
+ }
+ },
+ "DeslopWindow": {
+ "type": "object",
+ "required": ["text", "label", "aiAssistanceScore", "startLine", "endLine"],
+ "properties": {
+ "text": { "type": "string", "description": "The flagged passage text." },
+ "label": { "type": "string", "description": "Detection label for the passage, for example `AI-Generated`." },
+ "aiAssistanceScore": { "type": "number", "description": "AI-assistance score for the passage (0-1)." },
+ "confidence": {
+ "description": "Detection confidence, returned as either a label such as `High` or a numeric score.",
+ "oneOf": [
+ { "type": "string" },
+ { "type": "number" }
+ ]
+ },
+ "startLine": { "type": "integer", "description": "1-based start line of the passage in the original content." },
+ "endLine": { "type": "integer", "description": "1-based end line of the passage in the original content." },
+ "rewrites": {
+ "type": "array",
+ "description": "Suggested human rewrites of the passage.",
+ "items": {
+ "type": "object",
+ "required": ["text", "rationale"],
+ "properties": {
+ "text": { "type": "string", "description": "The rewritten passage." },
+ "rationale": { "type": "string", "description": "Why the rewrite reads more human." }
+ }
+ }
+ }
+ }
+ },
"AgentJob": {
"type": "object",
"properties": {
@@ -627,7 +762,7 @@
"bearerAuth": {
"type": "http",
"scheme": "bearer",
- "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard."
+ "description": "The Authorization header expects a Bearer token. Use an admin API key. This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard."
}
}
}
diff --git a/agent-context/.gitignore b/agent-context/.gitignore
new file mode 100644
index 0000000000..ba34fb68b6
--- /dev/null
+++ b/agent-context/.gitignore
@@ -0,0 +1,3 @@
+dist/
+node_modules/
+.DS_Store
diff --git a/agent-context/LICENSE b/agent-context/LICENSE
new file mode 100644
index 0000000000..dacb79ecce
--- /dev/null
+++ b/agent-context/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mintlify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/agent-context/README.md b/agent-context/README.md
new file mode 100644
index 0000000000..62c3453630
--- /dev/null
+++ b/agent-context/README.md
@@ -0,0 +1,60 @@
+# Mintlify agent context
+
+Single source of truth, maintained in the Mintlify documentation repository, for the Mintlify skill distributed through the Codex, Cursor, and Claude plugins.
+
+## Repository structure
+
+- `context/skills/mintlify/` contains canonical, client-neutral context.
+- `context/mcp-servers.json` contains canonical MCP names, URLs, and transport settings.
+- `targets/*.json` contains only client packaging differences such as MCP config file and schema names.
+- `scripts/build.mjs` renders self-contained plugin artifacts into `dist/`.
+- `scripts/sync-target.mjs` replaces only `skills/mintlify/` in a target repository.
+- `../.github/workflows/sync-agent-context.yml` opens generated sync pull requests in all three plugin repositories.
+
+Plugin manifests, assets, READMEs, and Cursor rules remain owned by their target repositories. This project generates the shared skill and each client's MCP configuration file.
+
+## Local development
+
+Requires Node.js 22 or newer and has no package dependencies.
+
+```bash
+npm test
+npm run check
+npm run build
+npm run status
+```
+
+Build one target by passing its ID:
+
+```bash
+node scripts/build.mjs codex
+```
+
+Preview a sync into a local checkout:
+
+```bash
+node scripts/sync-target.mjs codex ../../codex-plugin
+git -C ../../codex-plugin diff
+```
+
+The sync command replaces `skills/mintlify/`, writes the client-specific MCP configuration file, and writes `.mintlify-agent-context.json` with the source commit. It does not change any other plugin files.
+
+`npm run status` compares locally checked-out sibling plugin repositories with fresh builds and reports whether each one is current. Pass a workspace root as the final argument if the repositories do not share this repository's parent directory.
+
+## Publishing setup
+
+Create a GitHub App installed on these repositories:
+
+- `mintlify/codex-plugin`
+- `mintlify/cursor-plugin`
+- `mintlify/mintlify-claude-plugin`
+
+Grant the app repository **Contents: read and write** and **Pull requests: read and write** permissions. Add its client ID as the `CONTEXT_SYNC_APP_CLIENT_ID` Actions variable and its private key as the `CONTEXT_SYNC_APP_PRIVATE_KEY` Actions secret in the `mintlify/docs` repository.
+
+Every qualifying push to `main` validates the source and opens or updates the `automation/sync-agent-context` pull request in each repository. The workflow never pushes directly to a target's default branch.
+
+## Editing rules
+
+Edit shared knowledge and MCP definitions in `context/`, not in generated plugin copies. Put a value in `targets/` only when a client requires a different packaging format.
+
+The build rejects retired CLI commands. Tests verify that the skill, detailed references, and MCP definitions remain semantically identical across targets.
diff --git a/agent-context/context/mcp-servers.json b/agent-context/context/mcp-servers.json
new file mode 100644
index 0000000000..4ade053aa7
--- /dev/null
+++ b/agent-context/context/mcp-servers.json
@@ -0,0 +1,10 @@
+{
+ "Mintlify Search": {
+ "type": "http",
+ "url": "https://mintlify.com/docs/mcp"
+ },
+ "Mintlify Admin": {
+ "type": "http",
+ "url": "https://mcp.mintlify.com"
+ }
+}
diff --git a/agent-context/context/skills/mintlify/SKILL.md b/agent-context/context/skills/mintlify/SKILL.md
new file mode 100644
index 0000000000..edc49da650
--- /dev/null
+++ b/agent-context/context/skills/mintlify/SKILL.md
@@ -0,0 +1,240 @@
+---
+name: mintlify
+description: Comprehensive reference for building Mintlify documentation sites. Use when creating pages, configuring docs.json, adding components, setting up navigation, or working with API references. Routes to detailed reference files for all components and configuration options.
+---
+
+# Mintlify reference
+
+Reference for working on Mintlify projects. This file covers essentials that apply to every task. For detailed reference on specific topics, read the files listed in the reference index below.
+
+## Reference index
+
+Read these files **only when your task requires them**. They are in the `reference/` directory next to this file.
+
+| File | When to read |
+|------|-------------|
+| `reference/components.md` | Adding or modifying components (callouts, cards, steps, tabs, accordions, code groups, fields, frames, icons, tooltips, badges, trees, mermaid, panels, prompts, colors, tiles, updates, views). |
+| `reference/configuration.md` | Changing docs.json settings (theme, colors, logo, fonts, appearance, navbar, footer, banner, redirects, SEO, integrations, API config). Also covers snippets, hidden pages, .mintignore, custom CSS/JS, and the complete frontmatter fields table. |
+| `reference/navigation.md` | Modifying site navigation structure (groups, tabs, anchors, dropdowns, products, versions, languages, OpenAPI in nav). |
+| `reference/api-docs.md` | Setting up API documentation (OpenAPI, AsyncAPI, MDX manual API pages, extensions, playground config). |
+| `reference/cli.md` | Running CLI commands (dev, validate, analytics, workflow, score, broken-links, a11y, config, and all flags). |
+| `reference/product-context.md` | Before substantial content work (new site, broad restructure, first-time section setup) — check for and maintain `.mintlify/product-brief.md`. |
+
+## MCP servers
+
+Two Mintlify MCP servers are available. Use them alongside the reference files in this skill.
+
+### Mintlify Search
+
+Read-only access to Mintlify's published documentation. Use it when the reference files don't cover a specific detail, when you need an up-to-date component signature, or to verify an unfamiliar config option.
+
+Tools:
+- `search_mintlify` — Search the Mintlify knowledge base by query. Good for finding guides, examples, and API references.
+- `query_docs_filesystem_mintlify` — Browse the docs file tree (`ls`, `cat`, `grep`, `find`, etc.). Good for reading a specific docs page.
+- `submit_feedback` — Report a docs page that is incorrect, outdated, confusing, or incomplete.
+
+### Mintlify Admin
+
+Write access to a Mintlify project. Requires OAuth on first use. Complete authentication in the browser when prompted.
+
+Use this server when the user wants to edit their Mintlify content, restructure navigation, or open a pull request. All changes happen on a branch and must be reviewed before merging.
+
+Workflow: call `checkout` first (always), then use `read`/`search`/`edit_page`/`write_page`/`list_nodes`/`create_node`/`update_node`/`move_node`/`delete_node`/`update_config` to make changes, then call `save` to open a PR (or `discard_session` to abandon).
+
+Key tools:
+- **`checkout`** — Start a session on a branch (required first call). Returns an `editorUrl` to preview changes live.
+- **`list_branches`** — List existing branches; call before `checkout` to attach to one.
+- **`list_deployments`** — Discover which deployment(s) this connection can access.
+- **`read`** / **`search`** — Fetch a page's MDX or search across pages.
+- **`edit_page`** / **`write_page`** — Apply targeted edits or overwrite a page.
+- **`list_nodes`** / **`create_node`** / **`update_node`** / **`move_node`** / **`delete_node`** — Manage the navigation tree.
+- **`update_config`** — Modify `docs.json` (theme, nav roots, integrations, SEO).
+- **`diff`** — See all changes relative to `main`.
+- **`get_session_state`** — Check the current session's status.
+- **`save`** — Open a PR (`mode: "pr"`) or push to the branch (`mode: "commit"`).
+- **`discard_session`** — Drop all in-session changes.
+
+Keep each session focused on one change. Smaller sessions produce easier-to-review PRs. Open the `editorUrl` to watch changes render live.
+
+## Before you start
+
+Before substantial content work, read `reference/product-context.md` and check for `.mintlify/product-brief.md`.
+
+Read the project's `docs.json` file first. It defines the site's navigation, theme, colors, and configuration.
+
+Search for existing content before creating new pages. You may need to update an existing page, add a section, or link to existing content rather than duplicating.
+
+Read 2-3 similar pages to match the site's voice, structure, and formatting.
+
+## File format
+
+Mintlify uses MDX files (`.mdx` or `.md`) with YAML frontmatter.
+
+```
+project/
+├── docs.json # Site configuration (required)
+├── index.mdx
+├── quickstart.mdx
+├── guides/
+│ └── example.mdx
+├── openapi.yml # API specification (optional)
+├── images/ # Static assets
+│ └── example.png
+└── snippets/ # Reusable components
+ └── component.jsx
+```
+
+### File naming
+
+- Match existing patterns in the directory
+- If no existing files or mixed file naming patterns, use kebab-case: `getting-started.mdx`
+- Add new pages to `docs.json` navigation or they won't appear in the sidebar
+
+### Internal links
+
+- Use root-relative paths without file extensions: `/getting-started/quickstart`
+- Do not use relative paths (`../`) or absolute URLs for internal pages
+
+### Images
+
+Store images in an `images/` directory. Reference with root-relative paths. All images require descriptive alt text.
+
+```mdx
+
+```
+
+## Page frontmatter
+
+Include `title`, `description`, and `keywords` in frontmatter. `title` is technically optional (Mintlify generates one from the file path if omitted), but set it explicitly for clarity and SEO.
+
+```yaml
+---
+title: "Clear, descriptive title"
+description: "Concise summary for SEO and navigation."
+keywords: ["relevant", "search", "terms"]
+---
+```
+
+### Common frontmatter fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Page title in navigation and browser tabs. Auto-generated from the path if omitted. |
+| `description` | string | Brief description for SEO. Displays under the title. |
+| `sidebarTitle` | string | Short title for sidebar navigation. |
+| `icon` | string | Lucide, Font Awesome, or Tabler icon name. Also accepts a URL or file path. |
+| `tag` | string | Label next to page title in sidebar (e.g., "NEW"). |
+| `hidden` | boolean | Remove from sidebar. Page still accessible by URL. |
+| `mode` | string | Page layout: `default`, `wide`, `custom`, `frame`, `center`. |
+| `keywords` | array | Search terms for internal search and SEO. |
+| `api` | string | API endpoint for interactive playground (e.g., `"POST /users"`). |
+| `openapi` | string | OpenAPI endpoint reference (e.g., `"GET /endpoint"`). |
+
+For the complete list including `searchable`, `boost`, `deprecated`, `related`, `groups`, and more, read `reference/configuration.md`.
+
+## Quick component reference
+
+Below are the most commonly used components. For full props and all 25 components, read `reference/components.md`.
+
+### Callouts
+
+```mdx
+Supplementary information, safe to skip.
+Helpful context such as permissions or prerequisites.
+Recommendations or best practices.
+Potentially destructive actions or important caveats.
+Success confirmation or completed status.
+Critical warnings about data loss or breaking changes.
+```
+
+### Steps
+
+```mdx
+
+
+ Instructions for step one.
+
+
+ Instructions for step two.
+
+
+```
+
+### Tabs and code groups
+
+```mdx
+
+
+ ```bash
+ npm install package-name
+ ```
+
+
+ ```bash
+ yarn add package-name
+ ```
+
+
+```
+
+```mdx
+
+
+```javascript example.js
+const greeting = "Hello, world!";
+```
+
+```python example.py
+greeting = "Hello, world!"
+```
+
+
+```
+
+### Cards and columns
+
+```mdx
+
+
+ Card description text.
+
+
+ Card description text.
+
+
+```
+
+Use `` to arrange cards (or other content) in a grid. `cols` accepts 1-4.
+
+### Accordions
+
+```mdx
+
+ Content one.
+ Content two.
+
+```
+
+## CLI commands
+
+Install with `npm i -g mint`. Key commands: `mint dev` (local preview), `mint validate`, `mint broken-links`, `mint a11y`, `mint score`, `mint automations`, `mint deslop`, `mint new`, `mint signup`. Read `reference/cli.md` for full flags and subcommands.
+
+## Writing standards
+
+- Second-person voice ("you").
+- Active voice, direct language.
+- Sentence case for headings ("Getting started", not "Getting Started").
+- Sentence case for code block titles.
+- All code blocks must have language tags.
+- All images must have descriptive alt text.
+- No marketing language, filler phrases, or emoji.
+- Keep code examples simple, practical, and tested.
+
+## Common mistakes
+
+- Using `mint.json` — it is deprecated. The config file is always `docs.json`.
+- Missing language tag on a code block (use ` ```python `, not ` ``` `).
+- Using relative paths (`../page`) instead of root-relative (`/section/page`).
+- Forgetting to add new pages to `docs.json` navigation.
+- Images without alt text.
+- Adding file extensions to internal links (`/page.mdx` instead of `/page`).
diff --git a/agent-context/context/skills/mintlify/reference/api-docs.md b/agent-context/context/skills/mintlify/reference/api-docs.md
new file mode 100644
index 0000000000..ca44802f11
--- /dev/null
+++ b/agent-context/context/skills/mintlify/reference/api-docs.md
@@ -0,0 +1,141 @@
+# API documentation reference
+
+Setting up API documentation with OpenAPI, AsyncAPI, and MDX manual pages.
+
+## OpenAPI setup
+
+Add your OpenAPI spec to `docs.json`:
+
+```json
+"api": {
+ "openapi": "openapi.json"
+}
+```
+
+Multiple specs:
+
+```json
+"api": {
+ "openapi": ["openapi/v1.json", "openapi/v2.json"]
+}
+```
+
+Reference individual endpoints in navigation:
+
+```json
+{
+ "group": "Users",
+ "openapi": "openapi.json",
+ "pages": ["GET /users", "POST /users", "GET /users/{id}"]
+}
+```
+
+## OpenAPI extensions
+
+- `x-hidden`: Creates page but hides from navigation.
+- `x-excluded`: Completely excludes endpoint from docs.
+- `x-codeSamples`: Custom code examples per endpoint.
+
+```yaml
+paths:
+ /users:
+ get:
+ x-codeSamples:
+ - lang: "bash"
+ label: "List users"
+ source: |
+ curl https://api.example.com/users
+```
+
+## MDX manual API pages
+
+For endpoints without an OpenAPI spec:
+
+```yaml
+---
+title: "Create user"
+api: "POST https://api.example.com/users"
+---
+```
+
+Or with a base URL configured in `docs.json`:
+
+```yaml
+---
+title: "Create user"
+api: "POST /users"
+---
+```
+
+## AsyncAPI
+
+For WebSocket and event-driven APIs:
+
+```json
+"api": {
+ "asyncapi": "asyncapi.yaml"
+}
+```
+
+Reference channels in frontmatter:
+
+```yaml
+---
+title: "WebSocket channel"
+asyncapi: "/path/to/asyncapi.json channelName"
+---
+```
+
+## Playground configuration
+
+Control the API playground behavior in `docs.json`:
+
+```json
+"api": {
+ "playground": {
+ "display": "interactive",
+ "proxy": true
+ },
+ "examples": {
+ "languages": ["bash", "javascript", "python"],
+ "defaults": "all",
+ "prefill": false,
+ "autogenerate": true
+ },
+ "mdx": {
+ "server": "https://api.example.com",
+ "auth": {
+ "method": "bearer"
+ }
+ }
+}
+```
+
+- `playground.display`: `"interactive"`, `"simple"`, `"none"`, or `"auth"`.
+- `playground.proxy`: Route requests through Mintlify's proxy. Default: `true`.
+- `playground.credentials`: Include cookies and auth headers for cross-origin requests when proxy is `false`. Default: `false`.
+- `params.expanded`: Expand all parameters by default. `"all"` or `"closed"` (default).
+- `params.post`: OpenAPI schema field keys to surface as pills next to parameter names (array of strings).
+- `url`: Set to `"full"` to always show the full base URL.
+- `examples.languages`: Supported values — `bash` (cURL), `python`, `javascript`, `node`, `php`, `go`, `java`, `ruby`, `powershell`, `swift`, `csharp`, `dotnet`, `typescript`, `c`, `c++`, `kotlin`, `rust`, `dart`.
+- `examples.defaults`: `"required"` or `"all"` (include optional params).
+- `examples.prefill`: Pre-fill playground fields with spec example values. Default: `false`.
+- `examples.autogenerate`: Generate code samples from API specs. Default: `true`.
+- `mdx.auth.method`: `"bearer"`, `"basic"`, `"key"`, `"cobo"`.
+
+## Response rendering
+
+The playground renders responses automatically based on the `Content-Type` header:
+
+- `image/*` — rendered inline as an image.
+- `audio/*` — rendered with a built-in audio player.
+- `video/*` — rendered with a built-in video player.
+- All other types — displayed in a code block.
+
+## Parameter anchor links
+
+Every parameter in the playground has a clickable anchor link. Hover over a parameter name to reveal the link icon, then click to copy a direct URL to that parameter. The URL format is `your-docs-url/endpoint-path#parameter-name`. For nested parameters, the anchor includes the parent path.
+
+## Custom endpoint pages
+
+Use the `x-mint` extension in your OpenAPI spec to customize individual endpoint pages (metadata, playground behavior, additional content) while keeping all API documentation in one file. Alternatively, create individual MDX pages for full per-page control.
diff --git a/agent-context/context/skills/mintlify/reference/cli.md b/agent-context/context/skills/mintlify/reference/cli.md
new file mode 100644
index 0000000000..8c90f3534c
--- /dev/null
+++ b/agent-context/context/skills/mintlify/reference/cli.md
@@ -0,0 +1,67 @@
+# CLI reference
+
+Full reference for every `mint` CLI command and flag.
+
+Install with `npm i -g mint`.
+
+## Global flags
+
+Available on all commands.
+
+| Flag | Description |
+|------|-------------|
+| `--telemetry`, `-t` | Enable or disable anonymous usage telemetry. |
+| `--help`, `-h` | Display help for the command. |
+| `--version`, `-v` | Display the CLI version. Alias for `mint version`. |
+
+## Local development
+
+- `mint dev` — Start local preview at localhost:3000. `--port` sets the port. `--no-open` skips browser launch. `--groups ` mocks user groups. `--disable-openapi` skips OpenAPI processing. `--local-schema` allows locally-hosted OpenAPI files over HTTP.
+- `mint validate` — Strict build validation; exits non-zero on warnings or errors. `--groups ` mocks user groups. `--disable-openapi` skips OpenAPI processing. `--local-schema` allows local OpenAPI files.
+- `mint export` — Export a static site zip for air-gapped deployment. `--output ` sets the output path (default: `export.zip`). `--groups ` includes restricted pages. `--disable-openapi` skips OpenAPI processing.
+
+## Content quality
+
+- `mint broken-links` — Check for broken internal links. `--check-anchors` validates `#` anchors. `--check-external` checks external URLs. `--check-redirects` checks that redirect destinations in `docs.json` resolve. `--check-snippets` checks links inside `` components.
+- `mint a11y` — Accessibility checks (alt text, color contrast). `--skip-contrast` or `--skip-alt-text` to narrow scope.
+- `mint score [url]` — Score a docs site's AI/agent readiness. Checks llms.txt, MCP discoverability, robots.txt, sitemap, structured data, response latency, and more. Requires `mint login`. Defaults to your configured subdomain. `--format` accepts `table` (default), `plain`, or `json`.
+- `mint deslop [files...]` — Check pages for AI-sounding prose and get rewrite suggestions. Requires `mint login`. Without `files`, checks the `.md`/`.mdx` pages changed in your working tree (Git diff plus untracked files). Flags: `--format` (`table`/`plain`/`json`), `--subdomain`, `--threshold` (0-1, default 0.5), `--fix-whitespace` (normalizes trailing spaces, blank-line runs, and invisible Unicode outside code blocks/frontmatter).
+
+## Authentication
+
+- `mint login` — Authenticate your Mintlify account.
+- `mint logout` — Log out of your account.
+- `mint status` — Show current authentication status (CLI version, email, org, subdomain).
+- `mint signup [flags]` — Create a new Mintlify account from the terminal. Flags: `--firstName`, `--lastName`, `--company`, `--email`; omit any to enter it interactively. Waits until you click the emailed verification link before it logs you in — run as a background process in scripts.
+
+## Configuration
+
+- `mint config set ` — Persist a config value. Valid keys: `subdomain`.
+- `mint config get ` — Read a stored config value.
+- `mint config clear ` — Remove a stored config value.
+
+## Project setup
+
+- `mint new [directory]` — Scaffold a new Mintlify docs site. `--name` and `--theme` set initial config. `--template` selects a pre-defined template. `--force` overwrites an existing directory.
+
+## Automations
+
+All `mint automations` subcommands share these flags: `--subdomain`, `--format` (table/json; default: table). `mint workflow` and `mint workflows` continue to work as aliases.
+
+- `mint automations create` — Create an automation. Requires exactly one trigger: `--cron ` for scheduled or `--push-repo ` (repeatable) for push-triggered. Key flags: `--name`, `--type` (one of `changelog`, `source-code-agent`, `translations`, `writing-style`, `typo-check`, `broken-link-detection`, `seo-metadata-audit`, `assistant-docs-updates`, `contextual-feedback-docs-updates`; omit for custom), `--prompt`, `--context-repo` (repeatable, up to 10), `--automerge`, `--file ` (JSON/YAML file overrides inline flags).
+- `mint automations list` — List automations for the current deployment.
+- `mint automations delete ` — Delete an automation by ID. Use `mint automations list` to get the ID.
+
+## Maintenance
+
+- `mint update` — Update the CLI to the latest version.
+- `mint version` — Show installed CLI and client versions.
+
+## Telemetry
+
+The CLI collects anonymous usage telemetry by default. Opt out with `--telemetry false` or by setting either environment variable:
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `MINTLIFY_TELEMETRY_DISABLED` | `1` | Disable Mintlify CLI telemetry. |
+| `DO_NOT_TRACK` | `1` | Disable telemetry using the Console Do Not Track standard. |
diff --git a/agent-context/context/skills/mintlify/reference/components.md b/agent-context/context/skills/mintlify/reference/components.md
new file mode 100644
index 0000000000..7633f300e4
--- /dev/null
+++ b/agent-context/context/skills/mintlify/reference/components.md
@@ -0,0 +1,517 @@
+# Components reference
+
+Full syntax and props for all Mintlify components.
+
+## Callouts
+
+Styled alert boxes for important information.
+
+```mdx
+Supplementary information, safe to skip.
+Helpful context such as permissions or prerequisites.
+Recommendations or best practices.
+Potentially destructive actions or important caveats.
+Success confirmation or completed status.
+Critical warnings about data loss or breaking changes.
+```
+
+Custom callout with icon and color:
+
+```mdx
+
+ Custom callout with specific icon and color.
+
+```
+
+## Banner
+
+Not an MDX component. A site-wide announcement banner configured via the `banner` field in `docs.json`. See `reference/configuration.md`.
+
+## Accordions
+
+Expandable/collapsible content sections.
+
+```mdx
+
+ Hidden content revealed on click.
+
+```
+
+Group multiple accordions:
+
+```mdx
+
+ Content one.
+ Content two.
+
+```
+
+Props:
+- `title` (string, required): Header text.
+- `description` (string): Detail text below title.
+- `defaultOpen` (boolean, default: false): Initially expanded.
+- `icon` (string): Icon name.
+- `iconType` (string): Font Awesome style.
+
+## Cards
+
+Visual containers with titles, icons, and optional links.
+
+```mdx
+
+ Card description text.
+
+```
+
+```mdx
+
+ Card with image and custom CTA.
+
+```
+
+Props:
+- `title` (string, required): Card title.
+- `icon` (string): Icon name.
+- `iconType` (string): Font Awesome style.
+- `color` (string): Hex color for icon.
+- `href` (string): Link destination.
+- `horizontal` (boolean): Compact horizontal layout.
+- `img` (string): Image URL or path for top of card.
+- `cta` (string): Custom action button text.
+- `arrow` (boolean): Show link arrow.
+
+## Columns
+
+Multi-column responsive grid layout. Use with Cards or other content.
+
+```mdx
+
+ Content
+ Content
+ Content
+
+```
+
+Props:
+- `cols` (number, default: 2): Number of columns, 1-4.
+
+## Steps
+
+Numbered step-by-step procedures.
+
+```mdx
+
+
+ ```bash
+ npm i -g mint
+ ```
+
+
+ ```bash
+ mint new my-docs
+ ```
+
+
+ ```bash
+ mint dev
+ ```
+
+
+```
+
+Step props:
+- `title` (string): Step title.
+- `icon` (string): Icon name.
+- `iconType` (string): Font Awesome style.
+- `stepNumber` (number): Override automatic numbering.
+- `titleSize` (string, default: "p"): `"p"`, `"h2"`, or `"h3"`.
+
+## Tabs
+
+Switchable tabbed content sections.
+
+```mdx
+
+
+ ```bash
+ npm install package-name
+ ```
+
+
+ ```bash
+ yarn add package-name
+ ```
+
+
+```
+
+Tabs props:
+- `sync` (boolean, default: true): Sync tab selection with other tabs and code groups with matching titles.
+- `borderBottom` (boolean): Add bottom border and padding.
+
+Tab props:
+- `title` (string, required): Tab name.
+- `icon` (string): Icon name.
+- `iconType` (string): Font Awesome style.
+
+## Code groups
+
+Tabbed code examples in multiple languages. Tabs sync with `` components that have matching titles.
+
+```mdx
+
+
+```javascript example.js
+const greeting = "Hello, world!";
+console.log(greeting);
+```
+
+```python example.py
+greeting = "Hello, world!"
+print(greeting)
+```
+
+
+```
+
+For dropdown style instead of tabs:
+
+```mdx
+
+ ...code blocks...
+
+```
+
+## Expandables
+
+Show/hide nested properties. Primarily used in API documentation.
+
+```mdx
+
+ Unique identifier.
+ Display name.
+
+```
+
+Props:
+- `title` (string): Toggle label.
+- `defaultOpen` (boolean, default: false): Initially expanded.
+
+## Fields
+
+Document API parameters and response structures.
+
+### ParamField
+
+```mdx
+
+ Maximum number of results to return.
+
+
+
+ User email address.
+
+
+
+ Bearer token for authentication.
+
+```
+
+Props:
+- First parameter format: `query.name`, `path.name`, `body.name`, or `header.name`.
+- `type` (string): `number`, `string`, `boolean`, `object`. Append `[]` for arrays.
+- `required` (boolean): Mark as required.
+- `deprecated` (boolean): Mark as deprecated.
+- `default` (any): Default value.
+- `placeholder` (string): Playground input placeholder.
+
+### ResponseField
+
+```mdx
+
+ Unique user identifier.
+
+
+
+
+ Record ID.
+ Current status.
+
+
+```
+
+Props:
+- `name` (string, required): Field name.
+- `type` (string, required): Field type.
+- `required` (boolean): Required indicator.
+- `deprecated` (boolean): Deprecation flag.
+- `default` (string): Default value.
+- `pre` (string[]): Labels rendered before the field name.
+- `post` (string[]): Labels rendered after the field name.
+
+## Request and response examples
+
+Display code examples in the right sidebar on API pages.
+
+```mdx
+
+
+```bash cURL
+curl --request POST \
+ --url https://api.example.com/users \
+ --header 'Authorization: Bearer TOKEN'
+```
+
+```python Python
+import requests
+response = requests.post(
+ "https://api.example.com/users",
+ headers={"Authorization": "Bearer TOKEN"}
+)
+```
+
+
+
+
+
+```json 200
+{
+ "id": "usr_123",
+ "status": "active"
+}
+```
+
+
+```
+
+## Frames
+
+Styled container for images with optional captions.
+
+```mdx
+
+ 
+
+```
+
+Props:
+- `caption` (string): Text below image. Supports Markdown.
+- `hint` (string): Text above image.
+
+## Icons
+
+Display icons inline.
+
+```mdx
+
+ API
+ requests are sent over HTTPS.
+```
+
+Props:
+- `tip` (string, required): Tooltip text.
+- `headline` (string): Text above tip.
+- `cta` (string): Call-to-action link text.
+- `href` (string): Link URL (required if using `cta`).
+
+## Badge
+
+Inline labels and status indicators.
+
+```mdx
+
+ Active
+
+```
+
+Props:
+- `color` (string, default: "gray"): `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `purple`, `white`, `surface`.
+- `size` (string, default: "md"): `xs`, `sm`, `md`, `lg`.
+- `shape` (string, default: "rounded"): `rounded`, `pill`.
+- `icon` (string): Icon name.
+- `stroke` (boolean): Outline style instead of filled.
+- `disabled` (boolean): Reduced opacity.
+
+## Tree
+
+Display hierarchical file/folder structures.
+
+```mdx
+
+
+
+
+
+
+```
+
+Tree.Folder props:
+- `name` (string, required): Folder name.
+- `defaultOpen` (boolean, default: false): Expanded by default.
+- `openable` (boolean, default: true): Can expand/collapse.
+
+Tree.File props:
+- `name` (string, required): File name.
+
+## Mermaid diagrams
+
+Use mermaid code blocks for flowcharts, sequence diagrams, and more.
+
+````mdx
+```mermaid
+flowchart LR
+ A[Start] --> B{Decision}
+ B -->|Yes| C[Action]
+ B -->|No| D[Other action]
+```
+````
+
+## Panel
+
+Customize right sidebar content, replacing the table of contents.
+
+```mdx
+
+ Custom sidebar content goes here.
+
+```
+
+## Prompt
+
+Display copyable AI prompts.
+
+```mdx
+
+You are a technical writer. Generate a README for a Node.js project
+that includes installation, usage, and contributing sections.
+
+```
+
+Props:
+- `description` (string, required): Card header. Supports Markdown.
+- `actions` (array, default: ["copy"]): `"copy"`, `"cursor"`.
+- `icon` (string): Icon name.
+
+## Color
+
+Display color palettes with click-to-copy.
+
+```mdx
+
+
+```
+
+Table variant with rows:
+
+```mdx
+
+
+
+
+```
+
+## Tiles
+
+Visual preview cards, typically used in grid layouts.
+
+```mdx
+
+
+ 
+
+
+```
+
+Props:
+- `href` (string, required): Link destination.
+- `title` (string): Tile title.
+- `description` (string): Short description.
+
+## Update
+
+Display changelog entries and release notes.
+
+```mdx
+
+ ## What's new
+
+ - Added dark mode support
+ - Improved search performance
+
+```
+
+Props:
+- `label` (string, required): Date or version identifier.
+- `description` (string): Version or release name.
+- `tags` (string[]): Filterable tags.
+- `rss` (object): Custom RSS entry with `title` and `description`.
+
+## Visibility
+
+Show different content to humans (web UI) versus AI agents (Markdown output). Content marked `for="humans"` renders on the site but is excluded from `.md` URLs; content marked `for="agents"` is hidden on the site but included in Markdown output.
+
+```mdx
+
+ Click the **Get started** button in the top-right corner.
+
+
+
+ To create an account, call `POST /v1/accounts` with a valid email.
+
+```
+
+Props:
+- `for` (string, required): `"humans"` or `"agents"`.
+
+## View
+
+Language/framework-specific content sections that switch with a multi-view dropdown.
+
+```mdx
+
+ ```javascript
+ console.log("Hello from JavaScript!");
+ ```
+
+
+
+ ```python
+ print("Hello from Python!")
+ ```
+
+```
+
+Props:
+- `title` (string, required): View selector label.
+- `icon` (string): Icon name.
diff --git a/agent-context/context/skills/mintlify/reference/configuration.md b/agent-context/context/skills/mintlify/reference/configuration.md
new file mode 100644
index 0000000000..b062ca1be3
--- /dev/null
+++ b/agent-context/context/skills/mintlify/reference/configuration.md
@@ -0,0 +1,591 @@
+# Configuration reference
+
+Full docs.json settings, snippets, hidden pages, and custom CSS/JS.
+
+## docs.json
+
+The `docs.json` file controls the entire site. Required fields: `theme`, `name`, `colors.primary`, and `navigation`.
+
+### Splitting configuration with `$ref`
+
+Use `$ref` at any level of `docs.json` to load configuration from another JSON file. Useful for splitting large configs or sharing navigation across deployments.
+
+```json
+{
+ "$schema": "https://mintlify.com/docs.json",
+ "theme": "mint",
+ "name": "Your Docs",
+ "colors": { "primary": "#3B82F6" },
+ "navigation": {
+ "$ref": "./navigation.json"
+ }
+}
+```
+
+Rules:
+- `$ref` must be a relative path to a `.json` file.
+- When `$ref` resolves to an object, sibling keys in the same block take precedence over matching keys in the referenced file.
+- When `$ref` resolves to a non-object (e.g., an array), sibling keys are ignored.
+- Referenced files can contain their own `$ref` entries, resolved relative to that file.
+- Paths must stay within the project root. Circular references cause a build error.
+
+```json
+{
+ "$schema": "https://mintlify.com/docs.json",
+ "theme": "mint",
+ "name": "Your Docs",
+ "colors": {
+ "primary": "#3B82F6"
+ },
+ "navigation": {
+ "groups": [
+ {
+ "group": "Getting started",
+ "pages": ["index", "quickstart"]
+ }
+ ]
+ }
+}
+```
+
+## Complete frontmatter fields
+
+The SKILL.md file lists common frontmatter fields. Here is the complete set. All fields are optional; if `title` is omitted, Mintlify generates one from the file path (dashes and underscores become spaces, first letter capitalized).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Page title in navigation and browser tabs. Auto-generated from the path if omitted. |
+| `description` | string | Brief description for SEO. Displays under the title. |
+| `sidebarTitle` | string | Short title for sidebar navigation. |
+| `icon` | string | Lucide, Font Awesome, or Tabler icon name. Also accepts a URL or file path. |
+| `iconType` | string | Font Awesome icon style: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. |
+| `tag` | string | Label next to page title in sidebar (e.g., "NEW"). |
+| `hidden` | boolean | Remove from sidebar. Page still accessible by URL. Do not set to `false`; remove the field entirely to make a page visible again. |
+| `noindex` | boolean | Exclude from site search, sitemaps, search engine indexing, and AI assistant context. Still visible in navigation. |
+| `searchable` | boolean | Defaults to `true`. Set `false` to exclude the page from site search and AI assistant context while keeping it indexable externally and visible in navigation. |
+| `boost` | number | Multiply the page's in-product search ranking. Values above 1 prioritize, between 0 and 1 de-prioritize. No effect when `searchable: false`. |
+| `deprecated` | boolean | Show a "deprecated" label next to the page title. |
+| `hideFooterPagination` | boolean | Hide the previous/next navigation links at the bottom of the page. |
+| `related` | array or boolean | Related pages shown in the **Related topics** section, or `false` to hide it. Requires the Related pages add-on. |
+| `hideApiMarker` | boolean | Hide the HTTP method badge next to the page title in the sidebar. |
+| `contextual` | object | Override the site-wide contextual menu (`options`, `display`) for this page. `options: []` disables it. |
+| `groups` | string[] | Restrict the page to users in specific groups. Requires authentication configured first. |
+| `mode` | string | Page layout: `default`, `wide`, `custom`, `frame`, `center`. |
+| `keywords` | array | Search terms for internal search and SEO. |
+| `api` | string | API endpoint for interactive playground (e.g., `"POST /users"`). |
+| `openapi` | string | OpenAPI endpoint reference (e.g., `"GET /endpoint"`). |
+| `url` | string | External URL. Makes the nav entry link externally. |
+| `timestamp` | boolean | Override global timestamp setting for this page. |
+
+Any other key is accepted as custom frontmatter (e.g. `product: "API"`).
+
+## Page modes
+
+Control page layout with the `mode` frontmatter field.
+
+```yaml
+# Default: standard layout with sidebar and table of contents
+---
+title: "Page title"
+---
+
+# Wide: hides table of contents for extra horizontal space
+---
+title: "Page title"
+mode: "wide"
+---
+
+# Custom: blank canvas, only top navbar visible
+---
+title: "Page title"
+mode: "custom"
+---
+
+# Frame: like custom but keeps sidebar (Aspen, Almond, and Luma themes only)
+---
+title: "Page title"
+mode: "frame"
+---
+
+# Center: removes sidebar and TOC, centers content (Mint and Linden themes only)
+---
+title: "Page title"
+mode: "center"
+---
+```
+
+## Theme
+
+One of: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`, `aspen`, `sequoia`, `luma`.
+
+| Theme | Character |
+|-------|-----------|
+| `mint` | Classic, time-tested |
+| `maple` | Modern, clean, good for AI/SaaS |
+| `palm` | Sophisticated, fintech-focused |
+| `willow` | Stripped-back, minimal |
+| `linden` | Retro terminal, monospace |
+| `almond` | Card-based, minimalist |
+| `aspen` | Modern, supports complex navigation |
+| `sequoia` | Minimal, elegant, large-scale content |
+| `luma` | Clean, minimal design for polished documentation |
+
+## Colors
+
+```json
+"colors": {
+ "primary": "#3B82F6",
+ "light": "#F8FAFC",
+ "dark": "#0F172A"
+}
+```
+
+- `primary` (required): Main color, generally for emphasis in light mode.
+- `light`: Color for emphasis in dark mode.
+- `dark`: Color for buttons and hover states.
+
+All values must be hex codes starting with `#`.
+
+## Logo
+
+```json
+"logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg",
+ "href": "https://example.com"
+}
+```
+
+## Favicon
+
+Single file or light/dark variants:
+
+```json
+"favicon": "/favicon.ico"
+```
+
+```json
+"favicon": {
+ "light": "/favicon.png",
+ "dark": "/favicon-dark.png"
+}
+```
+
+## Icons
+
+```json
+"icons": {
+ "library": "lucide"
+}
+```
+
+Options: `"fontawesome"` (default), `"lucide"`, or `"tabler"`. You can only use one library per project. Individual icons can still use URLs or file paths regardless of this setting.
+
+## Fonts
+
+```json
+"fonts": {
+ "family": "Inter"
+}
+```
+
+Google Fonts load automatically by family name. For custom fonts:
+
+```json
+"fonts": {
+ "family": "CustomFont",
+ "source": "/fonts/CustomFont.woff2",
+ "format": "woff2",
+ "weight": 400,
+ "heading": {
+ "family": "HeadingFont",
+ "weight": 700
+ },
+ "body": {
+ "family": "BodyFont",
+ "weight": 400
+ }
+}
+```
+
+## Appearance
+
+```json
+"appearance": {
+ "default": "system",
+ "strict": false
+}
+```
+
+- `default`: `"system"`, `"light"`, or `"dark"`.
+- `strict`: Set `true` to hide the light/dark mode toggle.
+
+## Background
+
+```json
+"background": {
+ "image": {
+ "light": "/bg-light.svg",
+ "dark": "/bg-dark.svg"
+ },
+ "decoration": "gradient",
+ "color": {
+ "light": "#FFFFFF",
+ "dark": "#000000"
+ }
+}
+```
+
+- `decoration`: `"gradient"`, `"grid"`, or `"windows"`.
+
+## Styling
+
+```json
+"styling": {
+ "eyebrows": "breadcrumbs",
+ "latex": true,
+ "codeblocks": {
+ "theme": {
+ "light": "github-light",
+ "dark": "github-dark"
+ }
+ }
+}
+```
+
+- `eyebrows`: `"section"` (default) or `"breadcrumbs"`.
+- `latex`: Override automatic LaTeX detection.
+- `codeblocks`: `"system"` (default), `"dark"`, a Shiki theme name, or an object with `light`/`dark` themes.
+
+## Navbar
+
+```json
+"navbar": {
+ "links": [
+ {
+ "label": "Community",
+ "href": "https://example.com/community"
+ },
+ {
+ "type": "github",
+ "href": "https://github.com/example/repo"
+ }
+ ],
+ "primary": {
+ "type": "button",
+ "label": "Get Started",
+ "href": "https://example.com/start"
+ }
+}
+```
+
+Link types: omit `type` for standard text link, `"github"` for repo with star count, `"discord"` for server with online count.
+
+Primary button types: `"button"`, `"github"`, `"discord"`.
+
+## Footer
+
+```json
+"footer": {
+ "socials": {
+ "x": "https://x.com/example",
+ "github": "https://github.com/example",
+ "linkedin": "https://linkedin.com/company/example"
+ },
+ "links": [
+ {
+ "header": "Resources",
+ "items": [
+ { "label": "Blog", "href": "https://example.com/blog" }
+ ]
+ }
+ ]
+}
+```
+
+Valid social keys: `x`, `website`, `facebook`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `bluesky`, `threads`, `reddit`, `podcast`.
+
+## Banner
+
+```json
+"banner": {
+ "content": "Version 2.0 is live! [Learn more](/changelog)",
+ "dismissible": true,
+ "type": "info",
+ "color": {
+ "light": "#7C3AED",
+ "dark": "#5B21B6"
+ }
+}
+```
+
+- `content` (required): Supports basic Markdown (links, bold, italic). Custom components are not supported.
+- `dismissible`: Show a close button. Stays hidden for a user until content changes. Default: `false`.
+- `type`: Background style. `"info"` (primary color, default), `"warning"` (amber), `"critical"` (red).
+- `color`: Custom background hex. Overrides `type`. Object with `light` and `dark` keys, or a single hex string. Banner text is white — choose a dark enough background.
+
+Language-specific banners can be set inside the `navigation.languages` entries.
+
+## Variables
+
+Global content variables substituted at build time using `{{variableName}}` syntax in MDX files.
+
+```json
+"variables": {
+ "apiVersion": "v2",
+ "baseUrl": "https://api.example.com"
+}
+```
+
+Keys must be alphanumeric with hyphens only. Values are plain strings. Use in any `.mdx` file:
+
+```mdx
+The current API version is {{apiVersion}}.
+```
+
+## Redirects
+
+```json
+"redirects": [
+ {
+ "source": "/old-page",
+ "destination": "/new-page",
+ "permanent": true
+ }
+]
+```
+
+## Metadata
+
+```json
+"metadata": {
+ "timestamp": true
+}
+```
+
+Shows "Last modified on [date]" on all pages. Override per-page with `timestamp` frontmatter.
+
+## Interaction
+
+```json
+"interaction": {
+ "drilldown": false
+}
+```
+
+Controls whether clicking a navigation group navigates to its first page (`true`) or only expands/collapses (`false`).
+
+## SEO
+
+```json
+"seo": {
+ "metatags": {
+ "canonical": "https://docs.example.com",
+ "og:locale": "en_US"
+ },
+ "indexing": "navigable"
+}
+```
+
+- `indexing`: `"navigable"` (only nav pages) or `"all"` (every page including hidden).
+
+## Search
+
+```json
+"search": {
+ "prompt": "Search documentation..."
+}
+```
+
+## Contextual menu
+
+```json
+"contextual": {
+ "options": ["copy", "chatgpt", "claude", "cursor", "vscode"],
+ "display": "header"
+}
+```
+
+- `options` (required): First item is the default action. Built-in values: `"assistant"`, `"copy"`, `"view"`, `"chatgpt"`, `"claude"`, `"perplexity"`, `"grok"`, `"aistudio"`, `"devin"`, `"windsurf"`, `"mcp"`, `"add-mcp"`, `"cursor"`, `"vscode"`, `"devin-mcp"`. Custom objects accepted with `title`, `description`, `icon`, and `href` fields.
+- `display`: Where to show the menu. `"header"` (default) or `"toc"`.
+
+## Thumbnails
+
+```json
+"thumbnails": {
+ "appearance": "light",
+ "background": "/images/thumbnail-bg.svg",
+ "fonts": {
+ "family": "Inter"
+ }
+}
+```
+
+## Error handling
+
+```json
+"errors": {
+ "404": {
+ "redirect": true,
+ "title": "Page not found",
+ "description": "This page doesn't exist."
+ }
+}
+```
+
+## API configuration
+
+```json
+"api": {
+ "openapi": "openapi.json",
+ "playground": {
+ "display": "interactive",
+ "proxy": true
+ },
+ "examples": {
+ "languages": ["bash", "javascript", "python"],
+ "defaults": "all",
+ "prefill": false,
+ "autogenerate": true
+ },
+ "mdx": {
+ "server": "https://api.example.com",
+ "auth": {
+ "method": "bearer"
+ }
+ }
+}
+```
+
+- `openapi`: Single file, array, or object with `source` and `directory`.
+- `asyncapi`: Same format as `openapi` for AsyncAPI specs.
+- `playground.display`: `"interactive"`, `"simple"`, `"none"`, or `"auth"`.
+- `playground.proxy`: Route requests through Mintlify's proxy. Default: `true`.
+- `playground.credentials`: Include cookies and auth headers for cross-origin requests when proxy is `false`. Default: `false`.
+- `params.expanded`: Expand all parameters by default. `"all"` or `"closed"` (default).
+- `params.post`: OpenAPI schema field keys to surface as pills next to parameter names.
+- `url`: Set to `"full"` to always show the full base URL (default: only shown when multiple base URLs exist).
+- `examples.languages`: `bash`, `go`, `java`, `javascript`, `node`, `php`, `powershell`, `python`, `ruby`, `swift`.
+- `examples.defaults`: `"required"` or `"all"` (include optional params).
+- `examples.prefill`: Pre-fill playground fields with spec example values. Default: `false`.
+- `examples.autogenerate`: Generate code samples from API specs. Default: `true`.
+- `mdx.auth.method`: `"bearer"`, `"basic"`, `"key"`, `"cobo"`.
+
+## Integrations
+
+```json
+"integrations": {
+ "ga4": { "measurementId": "G-XXXXXXXXXX" },
+ "gtm": { "tagId": "GTM-XXXXX" },
+ "posthog": { "apiKey": "phc_xxx", "apiHost": "https://app.posthog.com" },
+ "amplitude": { "apiKey": "xxx" },
+ "mixpanel": { "projectToken": "xxx" },
+ "segment": { "key": "xxx" },
+ "clarity": { "projectId": "xxx" },
+ "fathom": { "siteId": "xxx" },
+ "hotjar": { "hjid": "xxx", "hjsv": "xxx" },
+ "logrocket": { "appId": "xxx" },
+ "heap": { "appId": "xxx" },
+ "pirsch": { "id": "xxx" },
+ "plausible": { "domain": "xxx", "server": "optional" },
+ "hightouch": { "writeKey": "xxx", "apiHost": "optional" },
+ "clearbit": { "publicApiKey": "xxx" },
+ "intercom": { "appId": "xxx" },
+ "frontchat": { "snippetId": "xxx" },
+ "telemetry": { "enabled": true },
+ "cookies": { "key": "consent_key", "value": "accepted" }
+}
+```
+
+## Reusable snippets
+
+Store reusable content in the `/snippets/` directory.
+
+### MDX snippets
+
+```mdx
+
+Before you begin, make sure you have:
+- Node.js 18+
+- A Mintlify account
+```
+
+Import in any page:
+
+```mdx
+import Prerequisites from "/snippets/prerequisites.mdx";
+
+ ');
+}
+
+const destination = path.resolve(process.cwd(), destinationArgument);
+const outputRoot = path.join(repositoryRoot, 'dist');
+await buildAll({ outputRoot, selectedIds: [targetId] });
+await copyTargetToRepository(targetId, destination, outputRoot);
+console.log(`Synced ${targetId} context to ${destination}`);
diff --git a/agent-context/targets/claude.json b/agent-context/targets/claude.json
new file mode 100644
index 0000000000..852b09b3ca
--- /dev/null
+++ b/agent-context/targets/claude.json
@@ -0,0 +1,6 @@
+{
+ "id": "claude",
+ "repository": "mintlify/mintlify-claude-plugin",
+ "mcpConfigFile": ".mcp.json",
+ "mcpConfigKey": "mcpServers"
+}
diff --git a/agent-context/targets/codex.json b/agent-context/targets/codex.json
new file mode 100644
index 0000000000..422c70a0c3
--- /dev/null
+++ b/agent-context/targets/codex.json
@@ -0,0 +1,6 @@
+{
+ "id": "codex",
+ "repository": "mintlify/codex-plugin",
+ "mcpConfigFile": ".mcp.json",
+ "mcpConfigKey": "mcp_servers"
+}
diff --git a/agent-context/targets/cursor.json b/agent-context/targets/cursor.json
new file mode 100644
index 0000000000..ca7fca11ee
--- /dev/null
+++ b/agent-context/targets/cursor.json
@@ -0,0 +1,6 @@
+{
+ "id": "cursor",
+ "repository": "mintlify/cursor-plugin",
+ "mcpConfigFile": "mcp.json",
+ "mcpConfigKey": "mcpServers"
+}
diff --git a/agent-context/test/build.test.mjs b/agent-context/test/build.test.mjs
new file mode 100644
index 0000000000..af2ed4710d
--- /dev/null
+++ b/agent-context/test/build.test.mjs
@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { buildAll, copyTargetToRepository } from '../scripts/lib.mjs';
+
+test('builds all client variants from one canonical skill', async () => {
+ const outputRoot = await mkdtemp(path.join(tmpdir(), 'mintlify-agent-context-test-'));
+
+ try {
+ await buildAll({ outputRoot });
+ const codex = await readFile(
+ path.join(outputRoot, 'codex', 'skills', 'mintlify', 'SKILL.md'),
+ 'utf8',
+ );
+ const cursor = await readFile(
+ path.join(outputRoot, 'cursor', 'skills', 'mintlify', 'SKILL.md'),
+ 'utf8',
+ );
+ const claude = await readFile(
+ path.join(outputRoot, 'claude', 'skills', 'mintlify', 'SKILL.md'),
+ 'utf8',
+ );
+ const codexMcp = JSON.parse(
+ await readFile(path.join(outputRoot, 'codex', '.mcp.json'), 'utf8'),
+ );
+ const cursorMcp = JSON.parse(
+ await readFile(path.join(outputRoot, 'cursor', 'mcp.json'), 'utf8'),
+ );
+ const claudeMcp = JSON.parse(
+ await readFile(path.join(outputRoot, 'claude', '.mcp.json'), 'utf8'),
+ );
+
+ assert.equal(cursor, codex);
+ assert.equal(claude, codex);
+ for (const skill of [codex, cursor, claude]) {
+ assert.match(skill, /Generated from mintlify\/docs\/agent-context/);
+ assert.match(skill, /### Mintlify Search/);
+ assert.match(skill, /### Mintlify Admin/);
+ assert.match(skill, /Complete authentication in the browser when prompted/);
+ assert.match(skill, /mint automations/);
+ assert.doesNotMatch(skill, /mint analytics|mint workflow|\{\{/);
+ }
+ assert.deepEqual(codexMcp.mcp_servers, cursorMcp.mcpServers);
+ assert.deepEqual(claudeMcp.mcpServers, cursorMcp.mcpServers);
+ assert.deepEqual(Object.keys(cursorMcp.mcpServers), [
+ 'Mintlify Search',
+ 'Mintlify Admin',
+ ]);
+ } finally {
+ await rm(outputRoot, { recursive: true, force: true });
+ }
+});
+
+test('sync replaces only generated context paths', async () => {
+ const root = await mkdtemp(path.join(tmpdir(), 'mintlify-agent-context-sync-test-'));
+ const outputRoot = path.join(root, 'dist');
+ const destination = path.join(root, 'plugin');
+
+ try {
+ await mkdir(path.join(destination, 'skills', 'mintlify'), { recursive: true });
+ await writeFile(path.join(destination, 'README.md'), 'target-owned\n');
+ await writeFile(path.join(destination, 'skills', 'mintlify', 'stale.md'), 'remove me\n');
+ await writeFile(path.join(destination, '.mcp.json'), '{"stale":true}\n');
+
+ await buildAll({ outputRoot, selectedIds: ['codex'] });
+ await copyTargetToRepository('codex', destination, outputRoot);
+
+ assert.equal(await readFile(path.join(destination, 'README.md'), 'utf8'), 'target-owned\n');
+ await assert.rejects(readFile(path.join(destination, 'skills', 'mintlify', 'stale.md')));
+ assert.match(
+ await readFile(path.join(destination, 'skills', 'mintlify', 'SKILL.md'), 'utf8'),
+ /### Mintlify Search/,
+ );
+ const mcpConfig = JSON.parse(await readFile(path.join(destination, '.mcp.json'), 'utf8'));
+ assert.deepEqual(Object.keys(mcpConfig.mcp_servers), [
+ 'Mintlify Search',
+ 'Mintlify Admin',
+ ]);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/agent/customize.mdx b/agent/customize.mdx
index 89dcf04a9d..623b46b0ff 100644
--- a/agent/customize.mdx
+++ b/agent/customize.mdx
@@ -7,8 +7,8 @@ keywords: ["AGENTS.md", "agent configuration", "custom instructions", "agent cus
Create a `.mintlify/AGENTS.md` file at the root of your documentation project to customize the agent's behavior (`Agents.md` is also an accepted filename).
- Place your `AGENTS.md` file inside the `.mintlify/` directory, not at the root of your project. If you store the file at the root of your project, your custom instructions are publicly accessible by the `/agents.md` path. The `.mintlify/` directory is not served publicly so your `AGENTS.md` file is not accessible when in that directory.
-
+ Place your `AGENTS.md` file inside the `.mintlify/` directory, not at the root of your project. If you store the file at the root of your project, your custom instructions are publicly accessible at the `/agents.md` path. The `.mintlify/` directory is not served publicly, so your `AGENTS.md` file is not accessible when in that directory.
+
If you must store your `AGENTS.md` file at the root of your project or any other directory, add it to your [`.mintignore`](/organize/mintignore) file to exclude it from your documentation site.
diff --git a/agent/index.mdx b/agent/index.mdx
index 4a7418ff5b..1c548adf6d 100644
--- a/agent/index.mdx
+++ b/agent/index.mdx
@@ -16,9 +16,7 @@ The agent is an AI tool that creates pull requests with proposed changes to your
- **Plans**: Creates a structured task list for complex documentation work.
- **Writes**: Generates or updates content following writing standards and best practices.
- **Validates**: Runs Mintlify CLI checks to ensure documentation builds correctly.
-- **Creates a PR**: Opens a pull request with proposed changes for review.
-
-All changes go through pull requests. The agent never commits directly to your main branch.
+- **Publishes changes**: Opens a pull request with proposed changes for review, or commits directly to your deployment branch, depending on your [review process setting](#choose-how-the-agent-publishes-changes).
## What you can do with the agent
@@ -39,10 +37,37 @@ Use the agent to:
By default, the agent opens pull requests attributed to the Mintlify bot. To attribute pull requests to you, connect your GitHub account on the [My profile](https://app.mintlify.com/settings/account) page of the dashboard.
+## Choose how the agent publishes changes
+
+By default, the agent opens a pull request for every change so your team can review it before it ships. If Mintlify hosts your deployment, the agent commits changes directly to your deployment branch so changes publish immediately.
+
+For deployments connected to your own Git provider, configure how the agent publishes changes in the **Configure Slack** setting on the [Automations](https://app.mintlify.com/products/automations) page of your dashboard:
+
+- **Create a pull request**: The agent commits to a new branch and opens a pull request against your deploy branch. Use this option when you want a human to review changes before they publish.
+- **Push to main**: The agent commits directly to your deploy branch, and changes publish as soon as the agent finishes. Use this option when you trust the agent to publish without review, for example on a staging deployment.
+
+
+ If your deploy branch has branch protection rules that block direct pushes, the **Review process** setting is hidden and the agent always opens a pull request.
+
+
## Connect repositories as context
The agent can only access repositories that you connect through the Mintlify GitHub App. Configure which repositories the agent can access in the agent panel **Settings** or in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).
+## Use a static IP for Git requests
+
+
+ Static agent egress requires an [Enterprise plan](https://mintlify.com/pricing?ref=static-agent-egress).
+
+
+If your Git provider restricts access with an IP allowlist, Mintlify can route Git requests from agent sandboxes through a static IP address.
+
+Contact Mintlify about the deployment that you want to enable static agent egress for. Once enabled, the static address applies to Git operations from the agent and automations, including cloning, fetching, and pushing connected repositories.
+
+
+ Static agent egress applies only to Git requests from agent sandboxes. Other outbound requests do not use this static IP address.
+
+
## Use AI tools alongside the agent
The agent works asynchronously through pull requests, but you can also use AI coding tools like Cursor or Claude Code locally for fast, iterative edits. Install the Mintlify [skill](/ai/skillmd) and connect the [MCP server](/ai/model-context-protocol) so your editor has the same context the agent uses.
diff --git a/agent/slack.mdx b/agent/slack.mdx
index 70ff8cd5e3..7ac2361e52 100644
--- a/agent/slack.mdx
+++ b/agent/slack.mdx
@@ -11,33 +11,29 @@ keywords: ["Slack integration", "Slack bot", "team collaboration", "agent integr
Use the agent in Slack to update your content, ask questions, and capture team knowledge. Mention the agent in a channel to use it collaboratively, or send it a direct message to use it privately.
- This page covers adding the agent as a bot to your Slack workspace. To give automations access to Slack channel content as a data source, see [Integrations](/automations/integrations).
+ The Slack app and third-party integrations work together. Install the Slack app to talk with the agent and give the agent and automation runs access to permitted Slack content. Then connect [integrations](/automations/integrations) so the agent can also use context from apps like Notion, Jira, Linear, or Google Drive.
## Connect your Slack workspace
-1. Go to the [Agent](https://app.mintlify.com/products/agent) page in your dashboard.
-2. In the "Agent settings" section, click **Install Slack app**.
-
- 
- 
-
-3. Follow the Slack prompts to install the `mintlify` app in your workspace and grant the requested permissions.
-4. Confirm the connection in your Mintlify dashboard to your Slack workspace.
-5. Test that the agent is working and responds when you:
- - Send a direct message to the agent.
- - Mention the agent with `@mintlify` in a channel.
-
Each Slack workspace can connect to only one Mintlify organization at a time. If you try to install the agent into a workspace that is already connected to a different organization, the installation fails with a "wrong organization" error. Uninstall the app from the other organization first, or use a different Slack workspace.
You can install the Slack agent even if you don't have a Mintlify-hosted deployment. The agent still works for question answering and conversations. Features that open pull requests require a connected repository.
+1. Navigate to the [Automations](https://app.mintlify.com/products/automations) page in your dashboard.
+2. Click **Connect Slack**.
+3. Follow the Slack prompts to install the `mintlify` app in your workspace and grant the requested permissions.
+4. Confirm the connection in your Mintlify dashboard to your Slack workspace.
+5. Test that the agent is working and responds when you:
+ - Send a direct message to the agent.
+ - Mention the agent with `@mintlify` in a channel.
+
- On Slack Enterprise Grid, installing the app to your organization is not enough. You must also install it to the specific workspace where you want to use the agent. If you skip this step, the agent appears available at the org level but does not respond in your workspace.
+ On Slack Enterprise Grid, you must install the app to the specific workspace where you want to use the agent. If you skip this step, the agent appears available at the organization level but does not respond in your workspace.
- To add the app to a workspace, open your org's app management page at a URL like `https://app.slack.com/manage//integrations/installed`, find the `mintlify` app, and install it to your workspace.
+ To add the app to a workspace, open your organization's app management page (a URL like `https://app.slack.com/manage//integrations/installed`). Find the `mintlify` app and install it to your workspace.
### Reconnect or reinstall the agent
@@ -80,15 +76,42 @@ Example questions:
- "How is our navigation structured?"
{/* vale Mintlify.FirstPerson = YES */}
+## Use connected integrations
+
+
+ Integrations require an [Enterprise plan](https://mintlify.com/pricing?ref=automations).
+
+
+The Slack agent can use connected third-party apps as read-only tools while answering questions or updating your documentation.
+
+- **Shared integrations** are available to everyone in your organization.
+- **Personal integrations** use the account connected by the teammate who is chatting with the agent. For example, a Google Drive search uses that teammate's Drive connection.
+
+You do not have to select integrations for each Slack conversation. Ask the agent to use a connected app naturally in your request, such as:
+
+- "Compare this Linear issue with the launch plan in the connected Google Drive."
+- "Update the migration guide based on the latest Jira issue."
+- "What does our Notion launch brief say about availability?"
+
+Prompt the agent to connect any integrations you want to use. Complete the authorization link it returns, then send another message in the same thread so the agent can confirm the connection.
+
+See [Integrations](/automations/integrations) for supported apps, connection scopes, and permissions.
+
## Update documentation
Use the agent to update your documentation with a new request or in an existing thread.
- **New request**: Send a direct message to the agent or mention `@mintlify` in a channel with instructions on what to update.
- **Existing thread**: Reply in the thread and mention `@mintlify` with instructions on what to update.
-- **With attachments**: Upload images, diagrams, code files, or other documents with your message. The agent automatically processes and includes them in your documentation. In a thread, the agent has access to images and files shared in earlier messages, so you can reference them in follow-up requests without reuploading.
+- **With attachments**: Upload images, diagrams, PDFs, SVGs, code files, or other documents with your message. The agent automatically processes and includes them in your documentation. In a thread, the agent has access to images and files shared in earlier messages, so you can reference them in follow-up requests without reuploading.
+
+The agent reads the context of the request or thread and updates your connected repository. Depending on your [review process setting](/agent/index#choose-how-the-agent-publishes-changes), the agent either opens a pull request or commits directly to your deployment branch.
+
+## Continue an automation run
+
+When an [automation](/automations) posts a [Slack notification](/automations/manage#slack-notifications) about a pull request it opened, reply in that thread and mention `@mintlify` to continue the work. The agent checks out the automation's branch and pushes your requested changes as follow-up commits to the same pull request, rather than opening a new one.
-The agent reads the context of the request or thread and creates a pull request in your connected repository with the updates.
+You can also share a link to an automation's pull request directly with the agent to continue it from a new thread.
## Reference other repositories
@@ -102,7 +125,7 @@ Example prompts:
- "Document the new endpoints added in `acme/backend#1234`."
- "What repositories do you have access to?"
-The agent treats cloned repositories as read-only. It uses them for context, but always opens pull requests against your documentation repository.
+The agent treats cloned repositories as read-only. It uses them for context, but only writes changes to your documentation repository.
## Track progress in real time
@@ -112,7 +135,7 @@ When the agent is making changes to your documentation, it provides live feedbac
- **Task progress**: When the agent breaks your request into multiple tasks, it displays a checklist so you can track progress on each one.
- **Questions**: If the agent needs more information, it presents options for you to select from or reply in the thread with a custom answer.
- **Interruptions**: If you send a follow-up message while the agent is still working, it stops the current task and starts on the new one.
-- **Completion**: When the agent finishes, it posts a summary with a link to the pull request and a link to open the changes in the web editor.
+- **Completion**: When the agent finishes, it posts a summary with a link to the pull request or commit and a link to open the changes in the web editor.
## Roles and permissions
diff --git a/agent/use-cases.mdx b/agent/use-cases.mdx
index ab4f53c1a0..a22574f035 100644
--- a/agent/use-cases.mdx
+++ b/agent/use-cases.mdx
@@ -44,7 +44,7 @@ For example: `@mintlify Generate a code example to make the authentication metho
## Add images or files to your docs
-Attach files or images directly to your Slack message when prompting the agent. The agent processes the attachment and includes it in the documentation.
+Attach files or images directly to your Slack message when prompting the agent. The agent processes the attachment and includes it in the documentation. Supported attachments include images, PDFs, SVGs, and other documents.
For example: `@mintlify Add this diagram to the architecture overview page` with the image attached to the message.
diff --git a/ai-native.mdx b/ai-native.mdx
index 73b1e4ceb0..006a2fc9c2 100644
--- a/ai-native.mdx
+++ b/ai-native.mdx
@@ -25,7 +25,7 @@ Configure popular tools like [Cursor](/guides/cursor), [Claude Code](/guides/cla
Your site is automatically optimized for AI tools and search engines to help users discover your documentation. All pages send their content as Markdown to AI agents instead of HTML, which helps these tools process your content faster and use fewer tokens. Every page is also available to view as Markdown by appending `.md` to the URL. Use the [visibility](/components/visibility) component to tailor content for each audience.
-Mintlify hosts `llms.txt` and `skill.md` files for your documentation. These industry-standard files help LLMs respond efficiently with relevant information to user queries and provide a list of capabilities for agents to use, so that users are more successful with your product.
+Mintlify hosts `llms.txt` and `skill.md` files for your documentation. These industry-standard files help LLMs respond efficiently with relevant information to user queries and provide a list of capabilities for agents to use. As a result, users are more successful with your product.
Teach your users how to install your `skill.md` file so they get better results when using your product with AI tools. Embed an installation prompt directly in your docs with the [`Prompt` component](/components/prompt):
diff --git a/ai/contextual-menu.mdx b/ai/contextual-menu.mdx
index 885e0b0f24..27cd50f70a 100644
--- a/ai/contextual-menu.mdx
+++ b/ai/contextual-menu.mdx
@@ -10,7 +10,7 @@ import IconsRequired from "/snippets/icons-required.mdx";
The contextual menu provides quick access to AI-optimized content and direct integrations with popular AI tools. When users click the contextual menu on any page, they can copy content as context for AI tools or open it in an AI conversation. Supported tools include ChatGPT, Claude, Perplexity, Google AI Studio, Grok, Devin, Devin Desktop, and any custom tool you configure.
- Pair the contextual menu with your hosted [`skill.md`](/ai/skillmd) file and [MCP server](/ai/model-context-protocol) so that users can install your product's full capabilities into their AI tools, not just the page they are reading.
+ Pair the contextual menu with your hosted [`skill.md`](/ai/skillmd) file and [MCP server](/ai/model-context-protocol). This lets users install your product's full capabilities into their AI tools, not just the page they are reading.
## Menu options
@@ -47,7 +47,7 @@ The contextual menu includes several pre-built options that you can enable by ad
## Enable the contextual menu
-Add the `contextual` field to your `docs.json` file and specify which options you want to include.
+Add the `contextual` field to your `docs.json` file and specify which options you want to include. Options appear in the menu in the order you list them.
```json
{
@@ -155,6 +155,25 @@ Example custom option:
}
```
+## Override on individual pages
+
+To override the global contextual menu on a specific page, add the `contextual` field to the page's frontmatter. Override the global contextual menu to surface page-specific actions like `download-pdf` on a terms of service page, or to hide the menu entirely on a landing page.
+
+The page-level `contextual` object replaces the global one for that page. Omit the field to inherit `docs.json`, or set `options: []` to disable the contextual menu on that page.
+
+```mdx
+---
+title: "Terms of Service"
+contextual:
+ options:
+ - copy
+ - download-pdf
+ display: header
+---
+```
+
+The same fields and validation rules apply as in `docs.json`, including [custom options](#add-custom-options) and the `display` setting. If a page override is invalid, Mintlify falls back to the global `contextual` configuration.
+
### Custom option examples
diff --git a/ai/llmstxt.mdx b/ai/llmstxt.mdx
index d4902743fa..65192dce23 100644
--- a/ai/llmstxt.mdx
+++ b/ai/llmstxt.mdx
@@ -35,6 +35,7 @@ An `llms.txt` file is a plain Markdown file that contains:
- **Site title** as an H1 heading.
- **Site description** as a blockquote summary below the title, sourced from the `description` field in your `docs.json` configuration.
+- **Custom agent instructions** as an `Agent Instructions` block after the description, if you set [`markdown.instructions`](/ai/markdown-export#custom-agent-instructions) in your `docs.json`.
- **Structured content sections** with links and a description of each page in your documentation.
- **API specification links** to your OpenAPI and AsyncAPI specs, if your documentation includes them.
diff --git a/ai/markdown-export.mdx b/ai/markdown-export.mdx
index 0771f6fec0..c49220b0bb 100644
--- a/ai/markdown-export.mdx
+++ b/ai/markdown-export.mdx
@@ -52,13 +52,44 @@ If you prefer to omit the spec from Markdown output, set `markdown.schema` to `f
}
```
-## Agent feedback
+## Custom agent instructions
-If you enable [agent feedback](/optimize/feedback#agent-feedback), Mintlify appends an `` block to each page's Markdown export that tells agents how to submit feedback about the page's content.
+To append your own guidance to the Markdown that Mintlify serves to AI agents, set `markdown.instructions` in your `docs.json`. Use it for site-wide directions like citing an API version, preferring a specific SDK, or following your terminology.
-Agents submit feedback by posting to the endpoint with the page path and feedback text.
+Provide a single string:
-Use agent feedback to improve your pages for agents based on what they find incorrect, outdated, or confusing.
+```json Example agent instructions string
+"markdown": {
+ "instructions": "Always cite the API version. Prefer the TypeScript SDK in examples."
+}
+```
+
+Or an array of strings, which Mintlify joins with line breaks:
+
+```json Example agent instructions array
+"markdown": {
+ "instructions": [
+ "Always cite the API version.",
+ "Prefer the TypeScript SDK in examples."
+ ]
+}
+```
+
+Mintlify renders your instructions as an `Agent Instructions` block in the Markdown output:
+
+```md Example rendered agent instructions
+> ## Agent Instructions
+> Always cite the API version.
+> Prefer the TypeScript SDK in examples.
+```
+
+The block appears in:
+
+- The Markdown export of every page, including API reference pages.
+- Your [`llms.txt`](/ai/llmstxt) file, after the site title and description.
+- Your `llms-full.txt` file.
+
+These instructions apply to every page. To tailor content for a single page or audience, use the [visibility](/components/visibility) component instead.
## Authentication
diff --git a/ai/mintlify-mcp.mdx b/ai/mintlify-mcp.mdx
index 267467b4bc..fe5fa9c5ae 100644
--- a/ai/mintlify-mcp.mdx
+++ b/ai/mintlify-mcp.mdx
@@ -1,15 +1,15 @@
---
title: "Admin Model Context Protocol (MCP) server"
sidebarTitle: "Admin MCP"
-description: "Give AI tools like Claude and Cursor write access to your Mintlify content and dashboard so they can edit pages, update settings, and open PRs."
-keywords: ["MCP", "write access", "AI", "editing", "Claude", "Cursor", "branch", "pull request"]
+description: "Give AI tools like Claude, ChatGPT, and Cursor write access to your Mintlify content and dashboard so they can edit pages, update settings, and open PRs."
+keywords: ["MCP", "write access", "AI", "editing", "Claude", "ChatGPT", "Cursor", "branch", "pull request"]
---
## About the admin MCP
The admin MCP server gives AI tools write access to your Mintlify content and settings. Use it to update content and access your dashboard. With the admin MCP, you can use your preferred AI tools to edit pages, restructure navigation, update `docs.json`, open pull requests, change settings, create workflows, and more.
-Connect any MCP client like Claude, Claude Code, or Cursor to the admin MCP server to collaborate on your Mintlify content and settings with the same tools you use to write code. When you use the admin MCP server, all changes happen on a branch and require a pull request to merge. If your organization has multiple deployments, a single admin MCP connection can access and switch between all of them.
+Connect any MCP client like Claude, Claude Code, ChatGPT, or Cursor to the admin MCP server to collaborate on your Mintlify content and settings with the same tools you use to write code. When you use the admin MCP server, all changes happen on a branch and require a pull request to merge. If your organization has multiple deployments, a single admin MCP connection can access and switch between all of them.
The admin MCP server allows AI tools to access your Mintlify dashboard. Treat it like a coworker with write access. Connect it only from trusted AI tools and review every pull request before merging.
@@ -32,7 +32,7 @@ Before connecting the admin MCP, confirm the following:
- **Mintlify account**: You need a Mintlify account with access to the project you want to edit. The OAuth session inherits your dashboard permissions, so admin-only actions (such as `update_config` on protected settings) require an admin role on the project.
- **Git provider access**: The Mintlify GitHub App or GitLab connection for the project must have write access to the deploy branch's repository. `save` opens PRs through the same integration used for normal deploys.
-- **MCP client**: An MCP-capable AI tool such as Claude, Claude Code, Cursor, or Codex.
+- **MCP client**: An MCP-capable AI tool such as Claude, Claude Code, ChatGPT, Cursor, or Codex.
## Connect to the admin MCP
@@ -63,6 +63,9 @@ You must have an interactive OAuth login against your Mintlify account to connec
On first use, Claude Code opens a browser window to complete the OAuth login. After authenticating, the session is reused for subsequent calls.
+
+ Install the official Mintlify connector from the [ChatGPT app directory](https://chatgpt.com/apps/mintlify-mcp/asdk_app_6a4d5a687f0881918be3cb8b4b93773d) and complete the OAuth login when prompted. Once installed, ChatGPT can call the Mintlify admin MCP tools during a chat.
+
1. Open the command palette with Command \+ Shift \+ P (Ctrl \+ Shift \+ P on Windows).
2. Search for **Open MCP settings** and click **Add custom MCP**.
@@ -114,7 +117,7 @@ Every admin MCP session binds to a single Git branch. The flow is:
Call `diff` at any time to see exactly what changed since `main`. Open the `editorUrl` in your dashboard to see the same changes rendered.
- Call `save` to flush the branch to Git. Use `mode: "pr"` (default) to open a pull request, or `mode: "commit"` to push directly to an existing PR branch.
+ Call `save` to flush the branch to Git. `mode: "auto"` (default) opens a pull request and, if the deployment's agent review setting is push-to-main and the deploy branch isn't protected, merges it immediately (response includes `merged: true`). Use `mode: "pr"` to always open a pull request and leave it open for review, or `mode: "commit"` to push directly to an existing PR branch without opening a new PR.
Call `discard_session` to drop all in-session changes and release the branch.
@@ -131,32 +134,32 @@ Every admin MCP session binds to a single Git branch. The flow is:
### Content
-- **`read`** — Fetch the full MDX of any page on the session branch.
-- **`search`** — Find lines matching a substring or regular expression across every page.
-- **`edit_page`** — Apply a targeted edit to a page.
-- **`write_page`** — Overwrite a page's full MDX content.
+- **`read`**: Fetch the full MDX of any page on the session branch.
+- **`search`**: Find lines matching a substring or regular expression across every page.
+- **`edit_page`**: Apply a targeted edit to a page.
+- **`write_page`**: Overwrite a page's full MDX content.
### Navigation
-- **`list_nodes`** — Walk the navigation tree with optional filters. Filter by `parentId` (use `recursive: true` to include all descendants), one or more node types, or any division scope: `language`, `version`, `tab`, `dropdown`, `anchor`, `product`, or `item`. Results paginate through an opaque `cursor`.
-- **`create_node`** — Add a new page, group, tab, anchor, version, language, product, or dropdown.
-- **`update_node`** — Update a node's properties in place (rename a group, change an icon, set a default version).
-- **`move_node`** — Move a node, including renaming a page's path.
-- **`delete_node`** — Remove a node from the navigation.
+- **`list_nodes`**: Walk the navigation tree with optional filters. Filter by `parentId` (use `recursive: true` to include all descendants), one or more node types, or any division scope: `language`, `version`, `tab`, `dropdown`, `anchor`, `product`, or `item`. Results paginate through an opaque `cursor`.
+- **`create_node`**: Add a new page, group, tab, anchor, version, language, product, or dropdown.
+- **`update_node`**: Update a node's properties in place (rename a group, change an icon, set a default version).
+- **`move_node`**: Move a node, including renaming a page's path.
+- **`delete_node`**: Remove a node from the navigation.
### Configuration
-- **`update_config`** — Modify `docs.json` (theme, navigation roots, integrations, SEO settings).
+- **`update_config`**: Modify `docs.json` (theme, navigation roots, integrations, SEO settings).
### Session
-- **`list_deployments`** — List the deployments your connection can access, returning each `{subdomain, name}`. Call this to discover which `subdomain` to pass to `checkout`.
-- **`checkout`** — Bind a session to a branch for a given deployment `subdomain`, or switch which deployment's session is active.
-- **`list_branches`** — List Git branches available for a deployment's project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name.
-- **`get_session_state`** — Inspect the current branch, edited files, and pending nav diff.
-- **`diff`** — List all changes between the session and `main`.
-- **`save`** — Open a pull request or commit to the session branch.
-- **`discard_session`** — Drop the session and its in-flight changes.
+- **`list_deployments`**: List the deployments your connection can access, returning each `{subdomain, name}`. Call this to discover which `subdomain` to pass to `checkout`.
+- **`checkout`**: Bind a session to a branch for a given deployment `subdomain`, or switch which deployment's session is active.
+- **`list_branches`**: List Git branches available for a deployment's project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name.
+- **`get_session_state`**: Inspect the current branch, edited files, and pending nav diff.
+- **`diff`**: List all changes between the session and `main`.
+- **`save`**: Open a pull request or commit to the session branch. If your deployment allows the agent to push to main and you have no branch protection rules, auto-merges the PR.
+- **`discard_session`**: Drop the session and its in-flight changes.
## Example prompts
@@ -198,6 +201,7 @@ Disconnect the admin MCP when you no longer want an AI tool to edit your project
- **Remove the connector in the client**:
- Claude: **Settings → Connectors**, then remove the admin MCP entry.
- Claude Code: `claude mcp remove mintlify`.
+ - ChatGPT: **Settings → Connectors**, then remove the Mintlify entry.
- Cursor: delete the `mintlify` entry from `mcp.json` and reload.
- Codex: delete the `[mcp_servers.mintlify]` block from `~/.codex/config.toml`.
diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx
index 783398ac4c..e1d31f8621 100644
--- a/ai/model-context-protocol.mdx
+++ b/ai/model-context-protocol.mdx
@@ -37,7 +37,7 @@ Your search MCP server provides three tools that agents can use:
- **Query docs filesystem**: Reads and navigates your site's virtual filesystem using shell-style commands. Use this to browse and retrieve content, or extract specific sections—including batch reads across multiple pages in a single call.
- **Submit feedback**: Reports a documentation issue back to your team when an agent finds a page that is incorrect, outdated, confusing, or incomplete. The agent supplies the page path and a description of the problem, which Mintlify records as unhelpful feedback in your analytics dashboard.
-Agents determine when to use each tool based on the context of the conversation. For example, an agent might first search your site to find relevant pages, then use the query docs filesystem tool to read the full content of the most relevant results, and call submit feedback if it discovers a problem with the page along the way.
+Agents determine when to use each tool based on the context of the conversation. For example, an agent might first search your site to find relevant pages, then use the query docs filesystem tool to read the full content of the most relevant results. If it discovers a problem with the page along the way, it can submit feedback.
### MCP resources
@@ -45,6 +45,8 @@ Your search MCP server also exposes your [skill.md files](/ai/skillmd) as MCP re
`Skill.md` resources appear in the search MCP server's resource list and contain the capability descriptions Mintlify generates or that you define in your [custom skill files](/ai/skillmd#custom-skill-files).
+If your documentation uses [authentication](/deploy/authentication-setup), skills with a `groups` field are only exposed to authenticated end users whose groups match. See [Restrict skills to user groups](/ai/skillmd#restrict-skills-to-user-groups).
+
### Search parameters
The MCP search tool supports optional parameters that AI applications use to control and refine search results.
diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index aef1014a68..d010dc5a69 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -7,7 +7,7 @@ boost: 3
Mintlify hosts a `skill.md` file at the root of your project that describes what AI agents can do with your product.
-The [skill.md specification](https://agentskills.io/specification) is a structured, machine-readable format that makes capabilities, required inputs, and constraints for products explicit so that agents can use them more reliably.
+The [skill.md specification](https://agentskills.io/specification) is a structured, machine-readable format that makes product capabilities, required inputs, and constraints explicit. Agents can then use those products more reliably.
Mintlify automatically generates a `skill.md` file for your project by analyzing your documentation with an agentic loop. This file stays up to date as you make updates to your documentation and requires no maintenance. You can optionally add a custom `skill.md` file to the root of your project that overrides the automatically generated one.
@@ -29,7 +29,7 @@ View your `skill.md` by appending `/skill.md` to your documentation site's URL.
## Use `skill.md` files with agents
- If you use a [reverse proxy](/deploy/reverse-proxy), configure it to forward `/skill.md`, `/.well-known/skills/*`, and `/.well-known/agent-skills/*` paths to your Mintlify subdomain.
+ If you use a [reverse proxy](/deploy/reverse-proxy), configure it to forward `/skill.md`, `/.well-known/skills/*`, and `/.well-known/agent-skills/*` paths to your Mintlify subdomain. See the [routing configuration](/deploy/reverse-proxy#routing-configuration) for the destination paths and caching policies.
When users connect to your MCP server, their agents can discover and use your `skill.md` files as [MCP resources](/ai/model-context-protocol#mcp-resources) without installing the skills separately.
@@ -42,6 +42,19 @@ npx skills add https://your-docs-domain.com
This adds your product's capabilities to the agent's context so it can take actions on behalf of users.
+{/* vale off */}
+
+
+Install the `skill.md` files from a Mintlify-hosted documentation site into my agent context so you know what this product can do.
+
+1. Ask me for the documentation site URL if I haven't provided one, then run `npx skills add ` with that URL.
+2. Print the list of skills that were installed, including each skill's name and description.
+3. Summarize the key capabilities in one paragraph so I know what you can now help me accomplish with this product.
+4. If any skill declares required inputs or constraints in its frontmatter, call them out before I ask you to use it.
+
+
+{/* vale on */}
+
Teach your users how to use `skill.md` files with agents so that they have better results using your product with their AI tools.
@@ -119,6 +132,7 @@ Custom `skill.md` files must start with YAML frontmatter.
| `compatibility` | string | Requirements or compatibility notes (for example, runtime dependencies). |
| `metadata` | object | Additional metadata as string key-value pairs (for example, `author` or `version`). |
| `allowed-tools` | string | Space-delimited list of pre-approved tools the skill may use (experimental). |
+| `groups` | array | Restrict the skill to specific authenticated user groups. See [Restrict skills to user groups](#restrict-skills-to-user-groups). |
```md Example frontmatter
---
@@ -132,6 +146,25 @@ metadata:
---
```
+### Restrict skills to user groups
+
+If your documentation uses [authentication](/deploy/authentication-setup), you can restrict a skill to specific user groups by adding a `groups` array to its frontmatter. Group filtering works the same way as [page visibility](/create/personalization#page-visibility): the skill is only exposed to authenticated users who belong to at least one of the listed groups.
+
+```md SKILL.md
+---
+name: admin-tools
+description: Internal operations for administrators.
+groups: ["admin"]
+---
+```
+
+Group-gated skills are:
+
+- Hidden from the public [skills discovery endpoints](#skills-discovery-endpoints) and the public `/skill.md` file.
+- Exposed as [MCP resources](/ai/model-context-protocol#mcp-resources) only to authenticated end users whose groups match. Users who don't match, and machine-to-machine clients without an end user, only see ungrouped skills.
+
+Skills without a `groups` field remain visible to everyone.
+
## Skills discovery endpoints
Mintlify hosts skills directories at `/.well-known/skills/` and `/.well-known/agent-skills/` that agents can use to discover and fetch your skill files programmatically.
diff --git a/analytics.openapi.json b/analytics.openapi.json
index b8b345fbd3..f18867b8d9 100644
--- a/analytics.openapi.json
+++ b/analytics.openapi.json
@@ -16,7 +16,7 @@
"bearerAuth": {
"type": "http",
"scheme": "bearer",
- "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard."
+ "description": "The Authorization header expects a Bearer token. Use an admin API key. This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard."
}
},
"schemas": {
@@ -646,7 +646,7 @@
"/v1/analytics/{projectId}/feedback": {
"get": {
"summary": "Get user feedback",
- "description": "Returns paginated user feedback with optional filtering",
+ "description": "Returns paginated user feedback with optional filtering\n\nAuthenticate with an admin API key.",
"tags": [
"Analytics"
],
@@ -762,7 +762,7 @@
"/v1/analytics/{projectId}/feedback/by-page": {
"get": {
"summary": "Get feedback by page",
- "description": "Returns feedback counts aggregated by documentation page path (thumbs up/down for contextual feedback, code snippet count, and total per page)",
+ "description": "Returns feedback counts aggregated by documentation page path (thumbs up/down for contextual feedback, code snippet count, and total per page)\n\nAuthenticate with an admin API key.",
"tags": [
"Analytics"
],
@@ -869,7 +869,7 @@
"/v1/analytics/{projectId}/assistant": {
"get": {
"summary": "Get assistant conversations",
- "description": "Returns paginated AI assistant conversation history",
+ "description": "Returns paginated AI assistant conversation history\n\nAuthenticate with an admin API key.",
"tags": [
"Analytics"
],
@@ -962,7 +962,7 @@
"/v1/analytics/{projectId}/assistant/caller-stats": {
"get": {
"summary": "Get assistant caller stats",
- "description": "Returns a breakdown of assistant query counts by caller type (web, API, and other) for the specified date range.",
+ "description": "Returns a breakdown of assistant query counts by caller type (web, API, and other) for the specified date range.\n\nAuthenticate with an admin API key.",
"tags": [
"Analytics"
],
@@ -1033,7 +1033,7 @@
"/v1/analytics/{projectId}/searches": {
"get": {
"summary": "Get search queries",
- "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).",
+ "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).\n\nAuthenticate with an admin API key.",
"tags": [
"Analytics"
],
@@ -1125,7 +1125,7 @@
"/v1/analytics/{projectId}/views": {
"get": {
"summary": "Get page views",
- "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.",
+ "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.\n\nAuthenticate with an admin API key.",
"tags": [
"Analytics"
],
@@ -1219,7 +1219,7 @@
"/v1/analytics/{projectId}/visitors": {
"get": {
"summary": "Get unique visitors",
- "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).",
+ "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).\n\nAuthenticate with an admin API key.",
"tags": [
"Analytics"
],
diff --git a/api-playground/adding-sdk-examples.mdx b/api-playground/adding-sdk-examples.mdx
index e6621c4949..0768d0d2e5 100644
--- a/api-playground/adding-sdk-examples.mdx
+++ b/api-playground/adding-sdk-examples.mdx
@@ -4,7 +4,7 @@ description: "Add SDK code samples to your API documentation with autogenerated
keywords: ["x-codeSamples", "SDK examples"]
---
-If your users interact with your API through an SDK rather than direct network requests, use the `x-codeSamples` extension to add code samples to your OpenAPI document. Mintlify displays the samples on your OpenAPI pages.
+If your users interact with your API through an SDK rather than direct network requests, add SDK code samples with the `x-codeSamples` extension. Mintlify displays these samples on your OpenAPI pages.
Add this property to any request method. It has the following schema.
@@ -20,7 +20,7 @@ Add this property to any request method. It has the following schema.
The source code of the sample.
-Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.
+The following example shows code samples for a plant tracking app that has both a Bash CLI tool and a JavaScript SDK.
```yaml
paths:
diff --git a/api-playground/graphql-setup.mdx b/api-playground/graphql-setup.mdx
new file mode 100644
index 0000000000..b27b54275e
--- /dev/null
+++ b/api-playground/graphql-setup.mdx
@@ -0,0 +1,103 @@
+---
+title: "GraphQL setup"
+description: "Generate reference pages for your GraphQL API from a schema definition file, with linked types and example queries, mutations, and responses."
+keywords: ["graphql", "schema", "sdl"]
+---
+
+## Add a GraphQL schema
+
+To create pages for your GraphQL API, you need a valid GraphQL schema in SDL (Schema Definition Language) format. Store the schema in your documentation repository or host it at an HTTPS URL that Mintlify can fetch.
+
+```graphql schema.graphql
+"An object with a stable identifier."
+interface Node {
+ id: ID!
+}
+
+type Organization implements Node {
+ id: ID!
+ name: String!
+}
+
+type Query {
+ organization(id: ID!): Organization
+}
+```
+
+## Auto-populate GraphQL pages
+
+To automatically generate pages for every query, mutation, and type in your schema, add a `graphql` property to a tab in your `docs.json`. Mintlify parses the schema and creates a page for each operation and named type.
+
+
+
+```json Local file
+"navigation": {
+ "tabs": [
+ {
+ "tab": "GraphQL API",
+ "graphql": "schema.graphql"
+ }
+ ]
+}
+```
+
+```json Remote URL
+"navigation": {
+ "tabs": [
+ {
+ "tab": "GraphQL API",
+ "graphql": "https://example.com/schema.graphql"
+ }
+ ]
+}
+```
+
+```json Custom directory
+"navigation": {
+ "tabs": [
+ {
+ "tab": "GraphQL API",
+ "graphql": {
+ "source": "schema.graphql",
+ "directory": "api/graphql"
+ }
+ }
+ ]
+}
+```
+
+
+
+The `graphql` property accepts either a string (a local path or HTTPS URL) or an object with the following fields.
+
+
+ You must declare `graphql` on a [tab](/organize/navigation#tabs). A tab with `graphql` may include `groups`, but no other navigation structures, such as `pages`, `versions`, or `languages`. It also cannot include an `openapi` or `asyncapi` property.
+
+
+
+ A local path to an SDL file in your documentation repository or an HTTPS URL to a hosted SDL file. Does not accept HTTP URLs.
+
+
+
+ The directory to store generated pages. Defaults to `graphql-reference`.
+
+
+## Generated pages
+
+Mintlify organizes generated pages into three sections under the tab you configured:
+
+- **Queries**: One page per field on your `Query` root type.
+- **Mutations**: One page per field on your `Mutation` root type.
+- **Types**: One page per named object, input, enum, interface, union, or scalar type.
+
+Each operation page shows the field description, arguments, return type, and links to any referenced types. Query and mutation pages also include a generated example operation, the required variables, and a sample JSON response.
+
+Type pages render the schema definition read-only, with linked field types so readers can navigate the graph.
+
+## Deprecations
+
+Fields and arguments that you mark with `@deprecated` in your schema display as deprecated on the generated pages. If you provide a deprecation reason, it appears next to the field.
+
+## Update your documentation
+
+Mintlify regenerates GraphQL reference pages when you run `mint dev` or when you push changes to your documentation repository. If your schema is hosted at an HTTPS URL, updates to the schema regenerate on the next build.
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index fadf690815..e371841bc4 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -147,9 +147,9 @@ Use the `x-default` extension on a security scheme to pre-fill the authenticatio
}
```
-The `x-default` extension supports `apiKey` and `http` bearer security scheme types. The value appears as the default input in the playground's authentication fields.
+The `x-default` extension supports `apiKey` and `http` bearer security scheme types. The value appears as the default input in the playground's authentication fields. Prefill for security schemes is unconditional and does not require any additional configuration.
-You can also use `x-default` on any schema property in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition.
+Use `x-default` on other schema properties in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. Unlike security schemes, prefill for non-security-scheme properties only takes effect when you set [`api.examples.prefill`](/organize/settings-api) to `true` in your [`docs.json`](/api-playground/overview#example-configuration).
## Let visitors download your spec
@@ -343,7 +343,7 @@ In this example, the navigation group displays as "User Management" but the gene
Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.
-The `openapi` field accepts either a path in your docs repo or a URL to a hosted OpenAPI document.
+The `openapi` field accepts either a path in your docs repo or a URL to a hosted OpenAPI document. Hosted specs must be reachable from the public internet.
When you use a URL for your OpenAPI spec, changes to the spec don't trigger a Git push, so your docs won't redeploy automatically. To keep your docs in sync, call the [Trigger deployment](/api/update/trigger) API endpoint in the same CI action that generates or updates your spec. This way your docs update automatically without needing to manually trigger a deployment from the dashboard.
diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx
new file mode 100644
index 0000000000..c414fb6e5e
--- /dev/null
+++ b/api-playground/sdk-reference-setup.mdx
@@ -0,0 +1,117 @@
+---
+title: "Generate SDK reference pages from doc-tool output"
+sidebarTitle: "SDK reference setup"
+description: "Publish SDK reference documentation in Mintlify from TypeDoc, DocFX, Javadoc, Sphinx, or phpDocumentor artifacts using the sdk navigation property."
+keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"]
+---
+
+Use the `sdk` navigation property to generate reference pages for your SDK libraries from the documentation tools you already run. Mintlify reads each tool's build artifact and creates a page for every class, interface, module, and function, with navigation groups, cross-page links, and search indexing included.
+
+## Supported formats
+
+| `format` | Tool | Artifact |
+| --- | --- | --- |
+| `typedoc` | [TypeDoc](https://typedoc.org) (TypeScript/JavaScript) | JSON export file |
+| `docfx` | [DocFX](https://dotnet.github.io/docfx/) (.NET) | `docfx metadata` output directory (ManagedReference YAML) |
+| `javadoc` | [Javadoc](https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html) (Java) | Standard doclet HTML directory |
+| `sphinx` | [Sphinx](https://www.sphinx-doc.org) (Python) | JSON builder output directory |
+| `phpdoc` | [phpDocumentor](https://phpdoc.org) (PHP) | `structure.xml` file |
+
+## Generate an artifact
+
+Run your documentation tool with a machine-readable output format. If you already publish generated docs from CI, this is usually a one-flag change to the same command.
+
+
+
+```bash TypeDoc
+npx typedoc --json typedoc.json src/index.ts
+```
+
+```bash DocFX
+docfx metadata docfx.json
+```
+
+```bash Javadoc
+javadoc -d javadoc-output -sourcepath src/main/java -subpackages com.example
+# Or download the published javadoc jar from Maven Central
+```
+
+```bash Sphinx
+python -m sphinx -b json docs/source artifacts/json
+```
+
+```bash phpDocumentor
+phpdoc -d src -t artifacts --template=xml
+```
+
+
+
+## Auto-populate SDK pages
+
+Add an `sdk` property to a tab in your `docs.json`. Mintlify parses the artifact and creates navigation groups and pages for the library.
+
+```json
+"navigation": {
+ "tabs": [
+ {
+ "tab": "SDK Reference",
+ "sdk": {
+ "format": "typedoc",
+ "source": "sdk-artifacts/typedoc.json",
+ "directory": "sdk/typescript"
+ }
+ }
+ ]
+}
+```
+
+
+ You must declare `sdk` on a [tab](/organize/navigation#tabs). A tab with `sdk` may include `groups`, but no other navigation structures, such as `pages`, `versions`, or `languages`. It also cannot include an `openapi`, `asyncapi`, or `graphql` property.
+
+
+
+ The documentation tool that produced the artifact: `typedoc`, `docfx`, `javadoc`, `sphinx`, or `phpdoc`.
+
+
+
+ Relative path to the artifact file or directory in your docs repository, or an HTTPS URL. Does not accept HTTP URLs.
+
+
+
+ The URL path prefix for generated pages. Defaults to `sdk-reference`.
+
+
+Add multiple tabs to document multiple libraries. Use a unique `directory` for each library to avoid route collisions.
+
+
+ Add your artifact directory to [`.mintignore`](/organize/mintignore) so Mintlify treats artifacts as build inputs rather than publishing them as static assets.
+
+
+## Generated pages
+
+Mintlify adds the generated navigation groups after any `groups` on the tab. The groups vary by format and may represent modules, packages, namespaces, or symbol types.
+
+Each generated page documents a class, interface, function, type, or other symbol from the artifact and links to related generated pages. If a converter produces pages that do not belong to a group, Mintlify collects them under a `Reference` group.
+
+## Use remote sources
+
+Set `source` to an HTTPS URL to fetch the artifact at build time instead of committing it to your docs repository.
+
+Single-file formats (`typedoc`, `phpdoc`) accept a direct file URL. Directory formats (`docfx`, `javadoc`, `sphinx`) accept a zip archive. Javadoc jars published to Maven Central work without repackaging:
+
+```json
+{
+ "tab": "Java SDK",
+ "sdk": {
+ "format": "javadoc",
+ "source": "https://repo1.maven.org/maven2/com/example/my-library/1.0.0/my-library-1.0.0-javadoc.jar",
+ "directory": "sdk/java"
+ }
+}
+```
+
+Remote artifacts have a 50 MB download limit and a 200 MB extracted size limit.
+
+## Keep references up to date
+
+Regenerate the artifact whenever your SDK changes. A common pattern is a CI job in each SDK repository that runs the documentation tool on release. The job either commits the artifact to your docs repository or uploads it to a stable URL that `source` points to.
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index c270c3b1c4..e5ac6f9418 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -75,7 +75,7 @@ If your API pages aren't displaying correctly, check these common configuration
requests, then all of these requests fail. To fix this, configure your reverse proxy to
allow `POST` requests to the `/_mintlify/api/request` path.
- Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.proxy` setting in the `docs.json`, as described in the [settings documentation](/organize/settings-api). When using this configuration, you must configure CORS on your server since requests come directly from users' browsers rather than through your proxy.
+ Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.proxy` setting in the `docs.json`. See the [settings documentation](/organize/settings-api) for details. When using this configuration, you must configure CORS on your server since requests come directly from users' browsers rather than through your proxy.
If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues:
@@ -106,6 +106,25 @@ If your API pages aren't displaying correctly, check these common configuration
2. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
3. **Manual vs automatic inclusion**: If you reference any endpoints from an OpenAPI spec, only the explicitly referenced operations appear in navigation. No other pages are automatically added. This includes operations that are referenced in child navigation elements.
+
+ Mintlify auto-generates a description for the `Authorization` field in the API playground based on the security scheme type. Override it by adding a `description` to the security scheme in your OpenAPI specification.
+
+ ```json {7}
+ {
+ "components": {
+ "securitySchemes": {
+ "bearerAuth": {
+ "type": "http",
+ "scheme": "bearer",
+ "description": "Your API key from the [dashboard](https://example.com/dashboard). Send it as `Bearer `."
+ }
+ }
+ }
+ }
+ ```
+
+ The `description` supports Markdown and replaces the auto-generated text on every endpoint that uses the security scheme.
+
When combining OpenAPI operations with regular documentation pages in navigation:
diff --git a/api/admin/deslop.mdx b/api/admin/deslop.mdx
new file mode 100644
index 0000000000..4903358ff8
--- /dev/null
+++ b/api/admin/deslop.mdx
@@ -0,0 +1,32 @@
+---
+title: "Detect AI-sounding prose"
+openapi: /admin-openapi.json POST /v1/deslop/{projectId}
+keywords: ["deslop", "AI detection", "slop", "prose", "content quality"]
+---
+
+This endpoint analyzes a documentation page for AI-generated prose and returns flagged passages with suggested human rewrites.
+
+Authenticate with an [admin API key](/api/introduction#admin-api-key).
+
+## Credits
+
+- Consumes 1 AI credit per checked page.
+- The endpoint skips pages under 50 words and does not charge for them. The response returns `skipped: "too_short"` with `creditsCharged: 0`.
+- If detection is temporarily unavailable, the endpoint returns `503` and doesn't consume a credit.
+- The endpoint accepts up to 30 requests per minute per client IP address.
+
+## Response
+
+Checked pages return a verdict (`predictionShort`), AI and human fractions, and a `windows` array of flagged passages. Each window includes a line range and can include one to three suggested rewrites.
+
+## Usage
+
+```bash
+curl -X POST https://api.mintlify.com/v1/deslop/{projectId} \
+ -H "Authorization: Bearer mint_xxxxx" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "path": "guides/quickstart.mdx",
+ "content": "# Quickstart\n\nWelcome to our comprehensive documentation..."
+ }'
+```
diff --git a/api/assistant/get-page-content.mdx b/api/assistant/get-page-content.mdx
index e64e3772c6..6e0b374812 100644
--- a/api/assistant/get-page-content.mdx
+++ b/api/assistant/get-page-content.mdx
@@ -6,4 +6,5 @@ keywords: [ "page", "content", "retrieve" ]
---
## Rate limits
+
- 10,000 requests per Mintlify organization per hour
diff --git a/api/introduction.mdx b/api/introduction.mdx
index e27b578335..f8d7bacd49 100644
--- a/api/introduction.mdx
+++ b/api/introduction.mdx
@@ -17,6 +17,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma
- [Get update status](/api/update/status): Get the status of an update and other details about your docs.
- [Trigger preview deployment](/api/preview/trigger): Create or update a preview deployment for a specific branch.
- [Trigger automation](/api/automations/trigger): Run a scheduled automation on demand.
+- [Detect AI-sounding prose](/api/admin/deslop): Analyze a page for AI-generated prose and get suggested human rewrites.
- [Create agent job](/api/agent/v2/create-agent-job): Create an agent job to automatically edit your documentation.
- [Get agent job](/api/agent/v2/get-agent-job): Retrieve the details and status of a specific agent job.
- [Send follow-up message](/api/agent/v2/send-message): Send a follow-up message to an existing agent job.
@@ -37,22 +38,23 @@ The Mintlify REST (Representational State Transfer) API enables you to programma
- **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger).
- **Preview deployments**: Create or update preview deployments programmatically in your CI/CD pipeline with [Trigger preview deployment](/api/preview/trigger).
- **On-demand automations**: Run scheduled automations from your CI/CD pipeline or release tooling with [Trigger automation](/api/automations/trigger).
-- **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2), [Search documentation](/api/assistant/search), and [Get page content](/api/assistant/get-page-content).
+- **Assistant integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2).
+- **Documentation retrieval**: Find and retrieve documentation for custom search experiences with [Search documentation](/api/assistant/search) and [Get page content](/api/assistant/get-page-content).
- **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message).
- **Analytics export**: Export feedback, assistant conversations, search analytics, page views, and visitor data for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get assistant caller stats](/api/analytics/assistant-caller-stats), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors).
## Authentication
-Generate API keys on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Each API key belongs to an organization--you can use keys across multiple deployments within the same organization.
+Generate API keys on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Each API key belongs to an organization—you can use keys across multiple deployments within the same organization.
You can create up to 10 API keys per hour per organization.
Mintlify uses two types of API keys, each scoped to a different set of endpoints:
-| Key type | Prefix | Use for |
-| --------------- | ----------- | ------------------------------------------------------------------------------------ |
-| Admin API key | `mint_` | Updates, agent jobs, and analytics exports. Server-side only. |
-| Assistant API key | `mint_dsc_` | Assistant endpoints (create message, search, get page content). Proxy in production. |
+| Key type | Prefix | Use for |
+| ----------------- | ----------- | --------------------------------------------------------------------------------------- |
+| Admin API key | `mint_` | Updates, agent jobs, and analytics exports. Server-side only. |
+| Assistant API key | `mint_dsc_` | Assistant messages, documentation search, and page content. Proxy in production. |
### Admin API key
@@ -62,6 +64,7 @@ Use the admin API key for deployment, triggering the agent, and analytics endpoi
- [Get update status](/api/update/status)
- [Trigger preview deployment](/api/preview/trigger)
- [Trigger automation](/api/automations/trigger)
+- [Detect AI-sounding prose](/api/admin/deslop)
- [Create agent job](/api/agent/v2/create-agent-job)
- [Get agent job](/api/agent/v2/get-agent-job)
- [Send follow-up message](/api/agent/v2/send-message)
@@ -80,12 +83,12 @@ The admin API key is a server-side secret. Do not expose it in client-side code.
### Assistant API key
- Do not directly embed the assistant API key in client-side code. Any visitor who extracts the key can send requests on your behalf, consuming credits and potentially triggering overage charges.
+ Do not directly embed the assistant API key in client-side code. Any visitor who extracts the key can call the assistant message endpoint on your behalf, consuming credits and potentially triggering overage charges.
- For production deployments, proxy assistant API requests through your own backend and store the key as a server-side environment variable. Routing requests through a proxy also lets you add rate limiting, authentication, and bot protection to prevent abuse.
+ For production deployments, proxy requests that use an assistant API key through your own backend and store the key as a server-side environment variable. Routing requests through a proxy also lets you add rate limiting, authentication, and bot protection to prevent abuse.
-Use the assistant API key for the assistant endpoints.
+Use the assistant API key to authenticate requests to the assistant, search, and page content endpoints.
- [Create assistant message](/api/assistant/create-assistant-message-v2)
- [Search documentation](/api/assistant/search)
@@ -94,5 +97,5 @@ Use the assistant API key for the assistant endpoints.
Assistant API keys begin with the `mint_dsc_` prefix.
- Calls using the assistant API token can incur costs: either using your assistant credits or incurring overages.
+ Search documentation and page content requests do not consume credits. Assistant message requests use credits and can incur overages.
diff --git a/api/static-export/overview.mdx b/api/static-export/overview.mdx
index 8fedfe0928..ca6f49497f 100644
--- a/api/static-export/overview.mdx
+++ b/api/static-export/overview.mdx
@@ -22,7 +22,7 @@ A static export runs as an asynchronous job. You start the job, poll for its sta
Poll [Get static export job status](/api/static-export/get-job-status) with the `jobId` until `status` is `completed`. The response includes live `progress` and `pageCount` while the job runs.
- Call [Generate export bundle](/api/static-export/generate-bundle) with the `jobId`. The API packages the export into a single archive and returns `bundleUrl`, a presigned S3 link to the static export bundle, alongside an `expiresAt` timestamp. Download the bundle before the `expiresAt` time. After the `espiresAt` time, call [Generate export bundle](/api/static-export/generate-bundle) again to get a fresh link. The underlying job and its files remain reusable. Only the link is time-limited.
+ Call [Generate export bundle](/api/static-export/generate-bundle) with the `jobId`. The API packages the export into a single archive and returns `bundleUrl`, a presigned S3 link to the static export bundle, alongside an `expiresAt` timestamp. Download the bundle before the `expiresAt` time. After the `expiresAt` time, call [Generate export bundle](/api/static-export/generate-bundle) again to get a fresh link. The underlying job and its files remain reusable. Only the link is time-limited.
diff --git a/assistant/customize.mdx b/assistant/customize.mdx
index 2269c8f3b1..7486d20a0b 100644
--- a/assistant/customize.mdx
+++ b/assistant/customize.mdx
@@ -7,8 +7,8 @@ keywords: ["assistant", "custom instructions", "Assistant.md", "system prompt",
Add a `.mintlify/Assistant.md` file at the root of your documentation project to give the assistant custom instructions that shape how it responds (`ASSISTANT.md` is also an accepted filename). The assistant uses these instructions as system-level context for every response.
- Place your `Assistant.md` file inside the `.mintlify/` directory, not at the root of your project. If you store the file at the root of your project, your custom instructions are publicly accessible by the `/assistant.md` path. The `.mintlify/` directory is not served publicly so your `Assistant.md` file is not accessible when in that directory.
-
+ Place your `Assistant.md` file inside the `.mintlify/` directory, not at the root of your project. If you store the file at the root of your project, your custom instructions are publicly accessible by the `/assistant.md` path. When placed inside `.mintlify/`, your `Assistant.md` file is not served publicly.
+
If you must store your `Assistant.md` file at the root of your project or any other directory, add it to your [`.mintignore`](/organize/mintignore) file to exclude it from your documentation site.
diff --git a/assistant/widget-preview.mdx b/assistant/widget-preview.mdx
new file mode 100644
index 0000000000..a4f8a2de12
--- /dev/null
+++ b/assistant/widget-preview.mdx
@@ -0,0 +1,11 @@
+---
+title: "Widget preview"
+description: "Host page for the live preview in the assistant widget playground."
+keywords: ["assistant", "widget", "preview"]
+mode: "custom"
+noindex: true
+---
+
+import { AssistantWidgetPreviewHost } from "/snippets/assistant-widget-preview-host.jsx";
+
+{children}
+);
+
+The [assistant](/assistant) answers questions on your Mintlify site. To embed the same capability on another site or web app, use the widget. With the widget, you can give your users access to AI chat trained on your content in your product dashboard, marketing site, support portal, or elsewhere.
+
+Add the widget to any website or web application with a hosted script. The widget owns its trigger and renders inside a closed Shadow DOM, which prevents your application styles from affecting the widget.
+
+The only required browser option is the public widget ID. Manage the enabled state, allowed origins, attachments, and bot protection in your dashboard. Set embed-specific starter questions and a support email in the browser configuration.
+
+## Prerequisites
+
+- A [Pro or Enterprise plan](https://mintlify.com/pricing?ref=assistant). The widget uses the same credits as the assistant.
+
+## Enable the widget
+
+1. Navigate to your deployment's [Widget](https://app.mintlify.com/settings/deployment/widget) page.
+2. Enable the widget.
+3. Add allowed origins where you embed the widget.
+4. Copy the widget ID.
+
+## Install and configure
+
+Use the playground to configure the presentation, visual options, and observer hooks for your widget. The installation code block updates as you change each option.
+
+
+ Replace `YOUR_WIDGET_ID` in the generated code with the widget ID from the [Widget](https://app.mintlify.com/settings/deployment/widget) page of your dashboard.
+
+
+After you add the generated code to your site, reload the page. Confirm the trigger appears, then click it and send a test question to verify the connection.
+
+
+
+
+ Module scripts defer and run in document order. Keep the hosted loader before the initialization block when you install the widget with HTML, or the widget fails to mount.
+
+
+## Open on initialization
+
+Set `defaultOpen` to `true` to open the widget immediately after its first mount:
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ defaultOpen: true,
+});
+```
+
+`defaultOpen` defaults to `false` and only applies to the first initialization. Calling `init()` again with the same widget ID and API endpoint does not reopen a widget that a visitor closed. Use `open()` and `close()` to control it after initialization.
+
+## Use a custom trigger
+
+Await `init()` before calling other methods. Keep the built-in trigger or open the configured presentation from any button in your application.
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ supportEmail: "hi@mintlify.com",
+ starterQuestions: [
+ "How do I get started with Mintlify?",
+ "How do I customize my docs?",
+ "How do I deploy my docs?",
+ ],
+});
+
+document.querySelector("#help-button").addEventListener("click", () => {
+ void window.MintlifyAssistant.open({
+ source: "help-button",
+ focus: true,
+ });
+});
+```
+
+To open the widget and immediately send a question, call `ask()`:
+
+```js
+await window.MintlifyAssistant.ask("How do I authenticate?", {
+ source: "authentication-guide",
+ open: true,
+ focus: true,
+});
+```
+
+Event metadata and requests include the `source` value, which lets you distinguish built-in interactions from your custom entry points.
+
+## Update a mounted widget
+
+Use `update()` to change appearance, labels, support email, starter questions, or hooks without clearing the current conversation. Only the supplied fields change.
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ theme: "dark",
+ accent: "#7c3aed",
+ },
+ labels: {
+ title: "Docs copilot",
+ trigger: "Ask docs",
+ },
+ supportEmail: "support@example.com",
+ starterQuestions: [
+ "How do I get started?",
+ "How do I manage my account?",
+ ],
+});
+```
+
+Pass `null` to restore a field or group to its default, remove the support email, or restore an empty starter-question list:
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ accent: null,
+ },
+ supportEmail: null,
+ starterQuestions: null,
+ hooks: null,
+});
+```
+
+Changing `identity` starts a new conversation. Changing the widget ID or API endpoint requires calling `destroy()` before a new `init()`.
+
+You can supply `supportEmail` and `starterQuestions` during initialization and change them later with `update()`. These values apply to the current embed and do not inherit from your Mintlify dashboard.
+
+## Configuration reference
+
+### `AssistantConfig`
+
+Pass this object to `init()`.
+
+| Option | Type | Description |
+| ------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| `id` | string | Public widget ID from the Mintlify dashboard. |
+| `endpoint` | string | Overrides the hosted widget API endpoint. |
+| `identity` | string | Signed end-user identity token. Omit for anonymous visitors. |
+| `nonce` | string | CSP nonce copied to resources created by the widget. |
+| `defaultOpen` | boolean | Opens the widget on its first initialization. The default is `false`. |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) | Visual and presentation overrides. |
+| `labels` | [`AssistantLabels`](#assistantlabels) | Customer-facing text overrides. |
+| `supportEmail` | string | Sets the support address shown in the widget toolbar for this embed. |
+| `starterQuestions` | string[] | Sets up to three empty-state prompts for this embed. |
+| `hooks` | [`AssistantHooks`](#assistanthooks) | Event and error observers. |
+
+### `AssistantAppearance`
+
+| Option | Values | Description |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `variant` | `widget`, `modal`, `panel` | Controls whether the assistant opens as an anchored popover, centered dialog, or responsive side panel. |
+| `theme` | `light`, `dark`, `system` | Sets the widget color scheme. The default is `system`. |
+| `accent` | CSS color | Sets the color of primary controls. |
+| `radius` | CSS border radius | Sets the panel radius, such as `18px`. |
+| `font` | CSS font family | Uses a font already loaded by your application. The default is Inter, which the widget bundles. |
+| `side` | `top`, `bottom`, `left`, `right`, `inline-start`, `inline-end` | Positions the built-in trigger on a screen edge. |
+| `align` | `start`, `center`, `end` | Aligns the trigger along its selected edge. |
+| `dismissOnInteractOutside` | boolean | Controls whether pointer or focus interactions outside close the assistant. |
+| `logo` | URL or `{ light, dark }` | Replaces the default Mintlify mark. |
+| `zIndex` | number | Changes the stacking order of the widget host. |
+
+Arbitrary CSS and neutral-palette overrides are not supported. The closed Shadow DOM protects both your application and the widget from cross-site style regressions.
+
+### `AssistantLabels`
+
+| Option | Values | Description |
+| ------------- | ----------------- | ------------------------------------------------------------------- |
+| `title` | string or `null` | Sets the panel header. The default is `Assistant`. |
+| `trigger` | string or `null` | Sets the compact widget and panel trigger text. |
+| `placeholder` | string or `null` | Sets the composer and modal trigger placeholder. |
+| `disclaimer` | string, `false`, or `null` | Sets the empty-state disclaimer. Pass `false` to hide it. |
+| `suggestions` | string or `null` | Sets the heading preceding starter questions. The default is `Suggestions`. |
+
+### `AssistantHooks`
+
+```js
+hooks: {
+ event(event) {
+ console.log(event.type, event.actor, event.source);
+ },
+ error(error) {
+ console.error(error.code, error.retryable, error.status);
+ },
+}
+```
+
+The `event` hook receives lifecycle and interaction metadata for `init`, `open`, `close`, `ask`, `update`, `reset`, `navigate`, and `destroy`. Events do not include question text, identity, session, or CAPTCHA tokens.
+
+The `error` hook receives a stable `code`, a `retryable` boolean, and an optional HTTP `status`. Exceptions thrown by either hook do not interrupt the widget.
+
+### `AssistantOpenOptions`
+
+Pass this optional object to `open()`.
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | Customer-defined attribution included in events and requests. |
+| `focus` | boolean | Focuses the composer after opening. The default is `true`. |
+
+### `AssistantAskOptions`
+
+Pass this optional object after the question string in `ask()`.
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | Customer-defined attribution included in events and requests. |
+| `open` | boolean | Opens the panel before sending. The default is `true`. |
+| `focus` | boolean | Focuses the composer when opening. The default is `true`. |
+
+### `AssistantUpdate`
+
+Pass this object to `update()`. Every field is optional, and `null` restores its default.
+
+| Option | Type | Description |
+| ------------------ | ------------------------------------------------------- | ----------------------------------------------------------------- |
+| `identity` | string or `null` | Changes the signed identity and starts a new conversation. |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) or `null` | Deep-patches appearance settings. |
+| `labels` | [`AssistantLabels`](#assistantlabels) or `null` | Deep-patches customer-facing text. |
+| `supportEmail` | string or `null` | Changes the support address. Pass `null` to remove it. |
+| `starterQuestions` | string[] or `null` | Changes up to three prompts. Pass `null` to restore an empty list. |
+| `hooks` | [`AssistantHooks`](#assistanthooks) or `null` | Deep-patches event and error observers. |
+
+## Browser API
+
+| Method | Parameter types | Description |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `init(config)` | [`AssistantConfig`](#assistantconfig) | Loads and mounts the widget. This is the readiness promise for every other method. |
+| `open(options)` | [`AssistantOpenOptions`](#assistantopenoptions) | Opens the configured presentation. |
+| `close()` | — | Closes the widget. |
+| `ask(question, options)` | string, [`AssistantAskOptions`](#assistantaskoptions) | Opens the widget if requested and sends a question. |
+| `update(config)` | [`AssistantUpdate`](#assistantupdate) | Deep-patches mutable identity, appearance, copy, and observer settings. |
+| `reset()` | — | Starts a fresh conversation. |
+| `destroy()` | — | Removes the widget and releases its browser resources. |
+
+Conversation snapshots remain private to the widget. Each method resolves to `void`.
+
+## Content Security Policy
+
+If your site uses a Content Security Policy, allow the origins required by your enabled widget features:
+
+| Directive | Source | Required for |
+| -------------------------------------------- | ----------------------------------- | --------------------------- |
+| `script-src` | `https://cdn.jsdelivr.net` | Widget loader and runtime |
+| `connect-src` | `https://api.mintlify.com` | Widget API |
+| `style-src` | `https://cdn.jsdelivr.net` | Widget style sheet |
+| `font-src` | `https://cdn.jsdelivr.net` | Optional bundled Inter font |
+| `script-src`, `connect-src`, and `frame-src` | `https://challenges.cloudflare.com` | Turnstile bot protection |
+| `script-src` | `https://js.hcaptcha.com` | hCaptcha bot protection |
+| `connect-src` and `frame-src` | `https://*.hcaptcha.com` | hCaptcha bot protection |
+
+A strict `script-src` policy must still authorize both the loader and initialization script. Passing `nonce` to `init()` propagates it only to resources the widget creates after initialization.
+
+
diff --git a/automations/create.mdx b/automations/create.mdx
index f65295bdf8..bfa9a66067 100644
--- a/automations/create.mdx
+++ b/automations/create.mdx
@@ -1,6 +1,6 @@
---
title: "Create a custom automation"
-description: "Create a custom Mintlify automation with a schedule or push trigger, context repositories, and an agent prompt to automate recurring documentation tasks."
+description: "Create a Mintlify automation that runs on a schedule, repository push, or integration event. Add context repositories and a custom agent prompt."
keywords: ["automation", "automate", "cron", "agent", "custom automation"]
---
diff --git a/automations/index.mdx b/automations/index.mdx
index bdc866e547..fb2e5e27cb 100644
--- a/automations/index.mdx
+++ b/automations/index.mdx
@@ -1,7 +1,7 @@
---
title: "Automations overview"
sidebarTitle: "Overview"
-description: "Automate content maintenance with Mintlify automations. Run the agent on a schedule or in response to GitHub and GitLab repository pushes."
+description: "Automate content maintenance with Mintlify automations by running the agent on a schedule, on repository pushes, or on connected integration events."
keywords: ["automation", "automate", "cron", "agent", "automations"]
boost: 5
---
@@ -10,23 +10,24 @@ boost: 5
Automations require a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=automations).
-Automations run the agent automatically on a schedule or in response to changes in a repository. Each automation defines a prompt for the agent and a trigger for when to run it. Automations support both GitHub and GitLab repositories with the same triggers, predefined automations, and update modes. Throughout this guide, "pull request" also refers to GitLab merge requests unless noted otherwise.
+Automations run the agent automatically on a schedule, in response to pushes to a repository, or when an event occurs in a connected integration. Each automation defines a prompt for the agent and a trigger for when to run it. Automations support both GitHub and GitLab repositories with the same triggers, predefined automations, and update modes. Throughout this guide, "pull request" also refers to GitLab merge requests unless noted otherwise.
When an automation runs, the agent reads your project content and any connected repositories, then follows the prompt to make updates.
- Use automations that run on a schedule for recurring tasks, like publishing changelogs or auditing SEO metadata.
+ Use automations that run on a schedule for recurring tasks, like publishing changelogs or improving content based on users' conversations with the [assistant](/assistant).
Use automations that trigger on content or code changes for reactive maintenance, like translations or updating content when source code changes.
## Trigger types
-Automations support three trigger types.
+Automations support four trigger types.
- **Content update**: Runs when content changes push to your Mintlify project repository, including pull request merges and direct pushes.
- **Code change**: Runs when a pull request merges in a connected source code repository.
- **Custom schedule**: Runs on a recurring schedule. Automations queue within 10 minutes of the scheduled time.
+- **Integration**: Runs when a selected event occurs in a connected shared integration. Requires an [Enterprise plan](https://mintlify.com/pricing?ref=automations).
Each automation has exactly one trigger. You cannot combine trigger types in a single automation.
@@ -35,7 +36,7 @@ Each automation has exactly one trigger. You cannot combine trigger types in a s
Automations group related changes into a single pull request instead of opening a separate one for every change. When a later run produces more changes that belong with an open pull request, the agent appends them to that pull request rather than opening a duplicate. Grouping behavior depends on the automation. See [Predefined automations](/automations/reference) for each automation's behavior.
- Draft changelog, Draft improvements from assistant conversations, Draft improvements from user feedback, Update from support feedback, and custom automations do not group or append. Each run opens its own pull request with the changes from that run. Update from support feedback can open up to three pull requests per run, one for each distinct theme it identifies.
+ Draft changelog, Fill gaps from assistant conversations, Improve docs from user feedback, Update from support feedback, and custom automations do not group or append. Each run opens its own pull request with the changes from that run. Update from support feedback can open up to three pull requests per run, one for each distinct theme it identifies.
## Reviewing automation pull requests
@@ -73,4 +74,4 @@ Each automation can run up to 500 times per day. Runs that fail do not count tow
Choose the right trigger, write effective instructions, and review results.
-
\ No newline at end of file
+
diff --git a/automations/integrations.mdx b/automations/integrations.mdx
index 5c7eb04d71..48d3d14d85 100644
--- a/automations/integrations.mdx
+++ b/automations/integrations.mdx
@@ -1,115 +1,153 @@
---
-title: "Automation integrations"
+title: "Integrations for the agent and automations"
sidebarTitle: "Integrations"
-description: "Connect Slack, Notion, Linear, Jira, Confluence, and other apps so automations can pull live context from the tools your team uses."
-keywords: ["integrations", "Slack", "Notion", "Linear", "Jira", "Confluence", "Salesforce", "Intercom", "Google Calendar", "Google Drive", "HubSpot", "Plain", "context", "automations", "Nango"]
+description: "Connect third-party apps so the Mintlify agent can use live context in Slack, during automation runs, or as a trigger for custom automations."
+keywords: ["integrations", "Slack agent", "Notion", "Linear", "Jira", "Confluence", "Salesforce", "Intercom", "Google Drive", "OneDrive", "Gmail", "Outlook", "HubSpot", "Plain", "automation trigger", "context"]
---
-
- Automation integrations require an [Enterprise plan](https://mintlify.com/pricing?ref=automation-integrations).
-
+Integrations connect the Mintlify agent to other tools your team uses. The agent can use connected apps while responding in Slack or running an automation. Events from some shared integrations can also start a custom automation.
-Integrations give [automations](/automations/index) access to context from other tools that your team uses. Once connected, an automation can search Slack threads, read Notion pages, look up Linear issues, and pull context from other apps to inform its content updates.
+| Integration use | What it does |
+| --- | --- |
+| **Slack agent** | Uses shared integrations and the personal integrations of the teammate who is chatting with the agent as context. |
+| **Automation tool** | Gives an automation read-only context from the shared integrations selected in its **Tools** setting. |
+| **Automation trigger** | Starts a custom automation when a selected event occurs in a supported shared integration. |
+
+
+ The [Mintlify Slack app](/agent/slack) is separate from the integrations on this page. Installing the Slack app adds the agent to your workspace and gives the agent and automation runs access to Slack content that the app can read. You do not connect Slack from the **Integrations** settings page or select it in an automation's **Tools** field.
+
## Connection scope
-Integrations connect in one of two ways:
+Integrations have one of two connection scopes.
+
+- **Shared integrations** connect once for your organization. The Slack agent can use them, and you can add them as tools to supported automations. Shared integrations that provide events can also trigger custom automations.
+- **Personal integrations** connect separately for each teammate. The Slack agent uses the personal account of the teammate who is chatting with it. Automations cannot use personal integrations as tools or triggers.
-- **Shared integrations** connect once for your entire organization and are available to your automations. Slack, Notion, Linear, Jira, Confluence, Salesforce, Intercom, HubSpot, and Plain all connect this way.
-- **Personal integrations** connect per user. Each teammate authorizes their own account. Google Calendar and Google Drive are personal.
+For example, if two teammates connect separate Google Drive accounts, each sees results from their own Drive when asking the agent a question in Slack.
-Personal integrations keep user-specific data, like calendar events, scoped to the user who connected the integration instead of shared across the organization.
+There is no limit to how many teammates can connect their own accounts. In a Slack thread with multiple participants, the agent uses the personal integrations of each message's sender.
## Connect an integration
-Admins and editors can connect shared integrations on behalf of the organization.
+Admins and editors can connect shared integrations on behalf of the organization. Each teammate connects their own personal integrations.
+
+### From the dashboard
1. Go to the [Integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard settings.
2. Find the integration you want to connect.
3. Click **Connect**.
-4. Follow the OAuth prompts to authorize Mintlify to access your account.
+4. Follow the authorization prompts.
+
+You can also connect an integration while configuring an automation. Select an unconnected app in the automation's **Tools** field, then complete the authorization flow.
-Some integrations open an additional configuration step before the connection completes. Jira, Confluence, and Salesforce ask for your workspace URL or subdomain before the OAuth flow begins. API-key providers like Plain prompt you to paste an API key.
+### From the Slack agent
+
+Prompt the agent to connect an app, such as "Connect Google Drive." The agent returns an authorization link in the Slack thread. Complete the authorization, then send another message in the same thread so the agent can confirm and use the connection.
## Supported integrations
-| Integration | Scope |
-| --- | --- |
-| Confluence | Shared |
-| Google Calendar | Personal |
-| Google Drive | Personal |
-| HubSpot | Shared |
-| Intercom | Shared |
-| Jira | Shared |
-| Linear | Shared |
-| Notion | Shared |
-| Plain | Shared |
-| Salesforce | Shared |
-| Slack | Shared |
+The dashboard shows the integrations currently available to your organization.
-## How automations use integrations
+| Integration | Scope | Available as an automation trigger |
+| --- | --- | --- |
+| Confluence | Shared | Yes |
+| Contentful | Shared | No |
+| Excel | Personal | No |
+| Figma | Shared | No |
+| Gmail | Personal | No |
+| Google Drive | Personal | No |
+| HubSpot | Shared | No |
+| Intercom | Shared | No |
+| Jira | Shared | Yes |
+| Linear | Shared | Yes |
+| Notion | Shared | Yes |
+| OneDrive | Personal | No |
+| OneNote | Personal | No |
+| Outlook | Personal | No |
+| Plain | Shared | No |
+| Salesforce | Shared | No |
+| Zendesk | Shared | Yes |
-Automations use connected integrations as tools. When an automation runs, the agent can search and retrieve content from the connected apps you enabled for that automation to build context for its updates.
+## Use integrations with the Slack agent
-To enable integrations for an automation, open the automation's settings and select the integrations you want the agent to use in the **Available integrations** section. Only integrations already connected for your organization appear in the list. See [Manage automations](/automations/manage#integrations) for details.
+After you install the [Mintlify Slack app](/agent/slack), the agent can use integrations while answering questions or updating your documentation. You do not have to select integrations for each Slack conversation.
-The agent only accesses integration data when it's relevant to the automation's task. It does not proactively read from connected apps.
+The agent can use:
-## Permissions and access
+- Shared integrations connected to your organization.
+- Personal integrations connected by the teammate who sent the request.
+- Slack channels and threads that the installed Mintlify app has permission to read.
-Each integration requests the OAuth scopes or API-key permissions it needs to search and retrieve content from the connected app. Mintlify requests read-only scopes wherever the provider offers them.
+For example, ask the agent to compare a Linear issue with a Google Drive product brief, answer a question using a Notion page, or update documentation using context from a Jira issue.
-Review the exact scopes during the OAuth consent screen before authorizing the connection. The consent screen lists every permission the integration receives, and you can revoke the connection at any time from the dashboard or from the connected app's own integrations settings.
+The agent only accesses integration data when it is relevant to the request.
-If your organization restricts which apps users can authorize, ask the relevant admin (such as your Slack or Google Workspace admin) to allow the Mintlify integration before connecting.
+## Use integrations as automation tools
-### What the agent can read from each app
+Automation tools give the agent additional context after an automation starts. You can select only shared integrations.
-The agent inherits the access of the account that authorized the connection. It can only read content that the authorizing user (for personal integrations) or the connected workspace account (for shared integrations) already has access to in the source app.
+1. Open the automation's settings.
+2. In **Tools**, select the integrations that the automation can use.
+3. Connect any selected integration that is not already connected.
+4. Save the automation.
-| Integration | Content the agent can access |
-| --- | --- |
-| Confluence | Pages and attachments in spaces the connected account can read |
-| Google Calendar | Events on calendars the connected user can view |
-| Google Drive | Files and folders the connected user can view, including shared drives |
-| HubSpot | CRM records (contacts, companies, deals, tickets) the connected account can read |
-| Intercom | Conversations, contacts, and help center articles the connected account can read |
-| Jira | Issues and comments in projects the connected account can read |
-| Linear | Issues, projects, and comments in teams the connected account can read |
-| Notion | Pages and databases explicitly shared with the Mintlify integration |
-| Plain | Threads and customer records accessible with the provided API key |
-| Salesforce | Standard and custom objects the connected account can read |
-| Slack | Public channels the workspace grants access to, plus private channels you add the Mintlify app to |
+If an integration is an automation trigger, it is always a tool for that automation. This lets the agent retrieve additional details after it receives the event that started the run.
-To narrow what the agent can see, restrict the connected account's permissions in the source app. For example, invite the Mintlify Slack app only to specific channels, or share only selected Notion pages with the integration.
+## Trigger an automation from an integration
-## Data retention after disconnect
+Custom automations can run when an event occurs in a supported shared integration.
-When you disconnect an integration, automations immediately lose the ability to read from that app. Mintlify doesn't retain a durable copy of integration content. The agent fetches data on each run through the live OAuth token or API key, so disconnecting cuts off future access.
+1. Create or open a custom automation.
+2. For **Trigger**, select **Integration**.
+3. Select or connect a shared integration.
+4. Select the **Trigger event**.
+5. Complete any additional event fields that appear.
+6. Save and turn on the automation.
-Content that appeared in past automation runs or pull requests stays in place (published pages, PR history). Edit or delete the pages directly if you also want that content removed.
+The supported events depend on the integration:
-## Troubleshoot a failed connection
+| Integration | Events |
+| --- | --- |
+| Confluence | Page created; content added to a space |
+| Jira | Issue created; issue updated; project created |
+| Linear | Issue created; issue updated; project created; project update posted |
+| Notion | Page created; page content updated |
+| Zendesk | Ticket created |
-If an integration stops working or shows an error in the dashboard, the underlying OAuth token usually expired, the connected app revoked it, or its required scopes changed.
+When the event occurs, Mintlify starts the automation and includes the event payload as context for the agent. Duplicate deliveries of the same event do not start duplicate runs.
-To restore access:
+## Permissions and access
-1. Go to the [Integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard settings.
-2. Find the affected integration and click **Configure**.
-3. Click **Disconnect**.
-4. Click **Connect**.
-5. Complete the OAuth flow.
+The agent has read-only access through third-party integration tools. It can search and retrieve content, but it cannot use these tools to create, edit, or delete data in the connected app.
+
+The agent inherits the access of the account that authorized the connection:
+
+- For a shared integration, it can read content available to the connected workspace account.
+- For a personal integration, it can read content available to the teammate who connected it.
+- For Slack, it can read public and private channels that include the Mintlify app.
+
+Authorization providers may group permissions differently. Review the authorization screen for the exact permissions requested before connecting an app. To narrow access, restrict the authorizing account's permissions or only grant the Mintlify app access to specific resources.
-For API-key providers like Plain, generate a new API key in the source app and paste it into the integration's configuration. If automations still can't access data after reconnecting, confirm that the authorizing user has permission to view the relevant content in the source app.
+If your organization restricts which apps users can authorize, ask the relevant administrator, such as your Google Workspace or Atlassian administrator, to approve the Mintlify app.
## Disconnect an integration
1. Go to the [Integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard settings.
-2. Find the connected integration you want to disconnect.
-3. Click **Configure**.
-4. Click **Disconnect**.
+2. Find the connected integration and click **Configure**.
+3. Click **Disable integration**.
+
+Disconnecting a shared integration removes it for everyone in your organization. Automations can no longer use it as a tool, and custom automations configured to use it as a trigger stop receiving new events.
+
+Disconnecting a personal integration only removes your connection. Other teammates keep their personal connections.
+
+## Troubleshoot a connection
+
+If an integration stops working:
-Disconnecting a shared integration removes it for everyone in your organization, and automations immediately lose access to that tool.
+1. Confirm that the authorizing account can still access the relevant content.
+2. Open the integration's **Configure** dialog and disable it.
+3. Connect the integration again and complete the authorization flow.
+4. If the connection is for the Slack agent, send another message in the original Slack thread.
-Disconnecting a personal integration only removes your own connection. Other teammates who have connected the same integration keep their access.
\ No newline at end of file
+If an administrator blocks authorization, ask your app or workspace administrator to approve Mintlify. The authorization screen shows the app identity and permissions that require approval.
diff --git a/automations/manage.mdx b/automations/manage.mdx
index fc91a6cc18..15672461b0 100644
--- a/automations/manage.mdx
+++ b/automations/manage.mdx
@@ -1,6 +1,6 @@
---
title: "Manage automations"
-description: "Enable, disable, trigger, and delete automations from your dashboard. Configure GitHub or GitLab triggers, schedules, context repos, and automerge."
+description: "Enable, disable, trigger, and delete automations from your dashboard. Configure repository, schedule, and integration triggers; context repos; and automerge."
keywords: ["cron", "push", "automerge", "context", "automation instructions", "trigger", "disable automation", "enable automation"]
---
@@ -44,6 +44,7 @@ Each automation has a default trigger that controls when it runs. To change the
- **Content update**: Runs whenever you push content to your project repository, including pull request merges and direct pushes.
- **Code change**: Runs when a pull request merges in a connected source code repository. You must specify at least one source repository.
- **Custom schedule**: Runs on a recurring schedule you define. Automations queue within 10 minutes of the scheduled time.
+- **Integration**: Runs when a selected event occurs in a connected shared integration. Available for custom automations. Select the integration and event, then complete any additional event fields that appear.
### Update mode
@@ -65,9 +66,11 @@ You can add up to 10 context repositories per automation. For each GitHub reposi
### Integrations
-For custom automations and the **Update from code changes** automation, you can enable connected [integrations](/automations/integrations). The agent then pulls context from tools like Slack, Notion, or Linear when the automation runs.
+For custom automations and supported predefined automations, enable connected [integrations](/automations/integrations). The agent pulls context from shared tools like Notion, Jira, or Linear when the automation runs.
-To enable integrations for an automation, open its settings and select the integrations you want the agent to use in the **Available integrations** section. Only integrations already connected for your organization appear in the list. Connect integrations on the [Integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard settings. See [Integrations](/automations/integrations) for more information.
+To enable integrations for an automation, open its settings and select the integrations you want to use in **Tools**.
+
+If you select **Integration** as the trigger for a custom automation, the triggering integration is always a tool for that automation. See [Integrations](/automations/integrations) for connection scopes, supported events, and permissions.
### Slack notifications
diff --git a/automations/reference.mdx b/automations/reference.mdx
index 42178f9eb8..5ac03b5980 100644
--- a/automations/reference.mdx
+++ b/automations/reference.mdx
@@ -12,14 +12,14 @@ Mintlify includes predefined automations for the most common documentation maint
| ---------- | --------------- | ------------------- | ------------- | ---------------------- |
| Update from code changes | Custom schedule (twice weekly) | Pull request | Supported | At least one source code repository |
| Draft changelog | Custom schedule | Pull request | Supported | None |
-| Draft improvements from assistant conversations | Custom schedule | Pull request | Not supported | None |
-| Draft improvements from user feedback | Custom schedule | Pull request | Not supported | Feedback collection enabled |
+| Fill gaps from assistant conversations | Custom schedule | Pull request | Not supported | None |
+| Improve docs from user feedback | Custom schedule | Pull request | Not supported | Feedback collection enabled |
| Update from support feedback | Custom schedule | Pull request | Supported | Intercom or Plain integration connected |
| Translate content | Content update | Direct merge | Not supported | At least one target language |
| Fix broken links | Content update | Pull request | Not supported | None |
-| Audit SEO metadata | Content update | Pull request | Not supported | None |
+| Fix SEO issues | Content update | Pull request | Not supported | None |
| Fix grammar & typos | Content update | Pull request | Not supported | None |
-| Apply style guide | Content update | Pull request | Not supported | None |
+| Enforce your style guide | Content update | Pull request | Not supported | None |
You can change all defaults from the automation's settings panel. See [Configurations](/automations/manage#configurations) for the available options.
@@ -41,11 +41,15 @@ You can enable [integrations](/automations/integrations) for this automation to
Creates a changelog entry on a recurring schedule. Add source code repositories as context so the agent has more detail about how your product changed. Without context repositories, the agent works from your content updates to write a changelog entry.
-### Draft improvements from assistant conversations
+
+
+### Fill gaps from assistant conversations
Reviews question trends from your [assistant](/assistant/index) to identify gaps in your content, then opens a pull request to address them. The more assistant conversations your users have, the more signal the agent has to work with. Run this automation on a recurring schedule to keep content aligned with what users want to know about your product.
-### Draft improvements from user feedback
+
+
+### Improve docs from user feedback
Reviews page [feedback](/optimize/feedback)—thumbs ratings and written comments—and updates content where users have reported problems. The agent focuses on pages with recurring negative signals rather than one-off feedback, so results improve as feedback accumulates.
@@ -55,7 +59,7 @@ You must enable feedback collection on the [Add-ons](https://app.mintlify.com/pr
Reviews resolved support conversations from [Intercom](/automations/integrations) or [Plain](/automations/integrations) to identify recurring gaps in your content, then opens a pull request to address them. The agent focuses on themes across multiple conversations rather than one-off questions, so results improve as your support volume grows.
-Select a single support platform when you configure the automation and connect it from the settings panel if it isn't already connected for your organization. Add source code repositories as context to help the agent tie support themes back to the product areas they describe.
+Select a single support platform when you configure the automation. Connect it from the settings panel if it isn't already connected for your organization. Add source code repositories as context to help the agent tie support themes back to the product areas they describe.
Each scheduled run groups related findings into up to three themes, and opens a separate pull request for each. Every run lists the resolved support conversations it reviewed and links back to the source platform, so you can trace every content suggestion to the underlying customer feedback.
@@ -81,14 +85,18 @@ To disable translations for a language, remove all files in that language's dire
Finds and fixes broken internal and external links whenever content changes push to your project repository. Useful to run after major content reorganizations or when external services you reference change their URLs.
-### Audit SEO metadata
+
-Audits and updates titles, meta descriptions, headings, and canonical tags whenever content changes. Add instructions to align the agent's suggestions with your SEO strategy or target keywords.
+### Fix SEO issues
+
+Checks and fixes titles, meta descriptions, headings, and canonical tags whenever content changes. Add instructions to align the agent's suggestions with your SEO strategy or target keywords.
### Fix grammar & typos
Finds and fixes typos, spelling mistakes, and grammar errors whenever content changes. Add instructions to specify exceptions for technical terms, product names, or intentional stylistic choices that the agent should not change.
-### Apply style guide
+
+
+### Enforce your style guide
-Applies voice, tone, and writing rules to content whenever it changes. Add instructions to define the specific rules you want enforced or link to your style guide. The more precise your instructions, the more consistent the results.
+Keeps voice, tone, and writing rules consistent whenever content changes. Add instructions to define the specific rules you want enforced or link to your style guide. The more precise your instructions, the more consistent the results.
diff --git a/changelog.mdx b/changelog.mdx
index a27e896edc..ec0fb1917a 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -5,6 +5,165 @@ rss: true
noindex: true
---
+
+
+ ## GraphQL and SDK references
+
+ - **GraphQL API reference pages:** Generate reference pages from a GraphQL SDL schema, with linked types and example queries, mutations, and responses. See [GraphQL setup](/api-playground/graphql-setup).
+ - **SDK reference generation:** Build SDK reference pages directly from the output of TypeDoc, DocFX, Javadoc, Sphinx, or phpDocumentor. See [SDK reference setup](/api-playground/sdk-reference-setup).
+
+ ## Editor and collaboration
+
+ - **Review flow:** Request review on a draft, leave feedback, and approve or request changes before publishing. Reviews now support non-deploy branches.
+ - **More ways to collaborate:** Start [comment threads](/editor/comments) on an entire page, mention yourself to leave a reminder, and use keybaord shortcuts Option + C or Option + S to comment on or suggest changes to selected text.
+ - **Faster, more available editing:** The editor renders without waiting for the Git file tree and people without GitHub write access can use the editor.
+
+ ## Automations, integrations, and Slack
+
+ - **Shared and personal integrations:** Give the Slack agent and automations read-only context from shared tools, or connect a personal account for the agent to use when you chat with it. See [integrations](/automations/integrations).
+ - **Integration triggers:** On Enterprise plans, trigger automations from third-party events such as a support ticket update.
+ - **Slack agent reads PR activity:** The [Slack agent](/agent/slack) now reads PR comments, reviews, and CI checks, and follows up in the thread after reverting a change based on feedback.
+
+ ## Analytics and data streaming
+
+ - **Analytics data warehouse streaming:** On Enterprise plans, stream analytics events to Amazon S3 in near real time, with controls for which event categories and deployments to include. See [analytics streaming](/optimize/analytics#stream-analytics-events).
+ - **Audit log streaming:** On Enterprise plans, stream audit events to Amazon S3 or Datadog for security monitoring and long-term retention. See [audit logs](/dashboard/audit-logs#stream-audit-logs).
+ - **Automation analytics dashboard:** A new analytics view for [automations](/automations) with metrics on pull requests and credit use.
+
+ ## Sites, deployments, and performance
+
+ - **Smaller navigation payloads:** Pages now load only the navigation data they need, improving performance most noticeably for large sites with multiple products, versions, or languages.
+ - **Better previews:** Preview deployments now serve search results. GitHub PR preview links open directly on the page you changed.
+ - **Deployment setup:** Use `mint add-domain` to configure a [custom domain](/customize/custom-domain) from the CLI.
+ - **`mint signup`:** Create a Mintlify account from the terminal, including agent-driven CLI workflows. See [CLI commands](/cli/commands#mint-signup).
+ - **Publishing controls:** Share a [changelog](/changelog) filtered to a specific tag, and ignore `.mintlify` during deploys by default except for `skills` and `specs`.
+ - **Simpler file trees:** Write [`FileTree`](/components/tree) components as nested Markdown lists to document folder structures with less markup.
+
+ ## Bug fixes
+
+ - **Search reliability:** Search preserves domain path casing, limits fuzzy fallback to near-typo matches, recovers stuck indexing jobs, retries transient uploads, and correctly tags pages listed across multiple products or versions.
+ - **Editor fidelity:** The editor preserves task lists, table escapes, LaTeX, callout types, video sources, image titles, inline code containing pipes, and block content nested in `Columns`.
+ - **Authenticated sites:** Search refreshes expired end-user JWTs, missing pages return genuine 404 responses, and password-auth settings render read-only when the feature is not entitled.
+ - **Previews, links, exports, and domains:** Preview builds surface branch deletion clearly, internal `.md` links respect `basePath`, PDF exports render in light mode, and subpath domain setup preserves its pending state while DNS is provisioning.
+ - **Themes and dashboard routing:** Center page mode works correctly in the `luma` and `sequoia` themes. The `maple` API side panel stays below tabs navigation. Duplicate page names no longer collide. Product redirects preserve authentication paths.
+
+
+
+
+
+ ## Page improvements
+
+ - **Related pages:** Display [related pages](/organize/related-pages) to help readers discover additional relevant content.
+ - **Per-page contextual menus:** Configure the [contextual menu](/ai/contextual-menu) per page in frontmatter to override the site-wide options.
+ - **Mermaid fullscreen mode:** Readers can expand [Mermaid diagrams](/components/mermaid-diagrams) into a fullscreen view for easier inspection of complex charts.
+ - **Improved scrolling:** Code blocks, API playgrounds, tables, sidebar navigation, and the table of contents now share a smoother cross-platform scrolling experience with larger touch targets.
+
+ ## Editor improvements
+
+ - **Drafts:** Work on unpublished changes without creating a branch or using any Git commands. See [Drafts](/editor/drafts) for more information.
+ - **Lock the deploy branch:** The editor now prompts you to lock your deploy branch if it detects branch protections.
+ - **Faster [editor agent](/editor) with better undo/redo:** Agent updates now stream in instantly, navigation is faster, and content and navigation-tree changes are undoable and redoable.
+ - **Collapsible heading state persists per user:** Your expanded and collapsed section preferences carry across editor sessions.
+ - **Visibility component in the editor:** The [visual editor](/editor) now supports the [`Visibility`](/components/visibility) component so you can author separate content for humans and AI agents without leaving the editor.
+ - **Hidden pages CTA:** A new banner in the editor calls out pages hidden from navigation so you can identify and manage them.
+
+ ## Sites and dashboard
+
+ - **Faster deployment queues:** Preview deployments can now run more builds concurrently to reduce queue times.
+ - **Resend member invitations:** Resend outstanding invitations to new organization members from the dashboard.
+ - **Better signup feedback:** Signup now reports subdomain availability and suggests an available subdomain when your first choice is taken.
+ - **Skipped deployment statuses:** The dashboard now shows when a deployment update was skipped instead of leaving its status unclear.
+ - **Trailing-slash SEO config:** New `seo.trailingSlash` option in [`docs.json`](/organize/settings-seo) enforces consistent trailing-slash URLs across your site.
+
+ ## Automations and Slack agent
+
+ - **Agent configuration moved into Automations:** Agent settings are now on the [Automations](/automations) page.
+ - **Continue automation PRs from Slack threads:** The Slack agent can pick up an automation PR conversation directly from workflow notification threads.
+ - **Respect repo conventions:** Agent PRs now honor your repo's PR template and `AGENTS.md` file.
+ - **Slack connect success modal:** The agent settings page shows a confirmation modal after you connect Slack.
+ - **Respect `.mintignore` on push deploys:** Push deployments now respect your `.mintignore` file, matching preview and CI behavior.
+
+ ## Analytics
+
+ - **New Analytics dashboard:** A redesigned analytics experience. Consolidated overview and traffic sections, a unified CSV export menu, synced date-range selectors, and a new feedback section.
+
+ ## Bug fixes
+
+ - Fixed OAuth redirect URIs on preview deployments so authenticated docs sign-in works on `.mintlify.site` preview hosts.
+ - Fixed an MDX caching issue so that after a parse failure, subsequent edits recover cleanly.
+ - MCP server "copy primary URL" button now shows a confirmation toast.
+ - AsyncAPI playground correctly sends header-based auth as the `Sec-WebSocket-Protocol` subprotocol.
+ - Rankings page views in analytics aggregate human and agent traffic, and zero-result delta colors reflect the correct direction.
+ - Reduced assistant errors while a response is streaming.
+ - Assistant chat history now preserves response text when a response ends with a tool call.
+ - Mermaid diagram actions now show on hover as expected.
+ - Version switcher is scoped to the versions available in the current dropdown.
+ - Navigation-level `public: false` settings are now respected in authentication metadata.
+ - Long chat-history messages are truncated instead of horizontally scrolling.
+ - Static assets and favicons now send `X-Robots-Tag: noindex` to keep them out of search results.
+ - `BreadcrumbList` JSON-LD no longer emits empty list items.
+
+
+
+
+
+ ## Custom domain, subdomain, and subpath hosting
+
+ - **Improved setup for custom domain, subdomain, and subpath hosting:** Updated UI and steps on the [Domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page. See [Custom domain](/customize/custom-domain) and [Host at a subpath](/deploy/docs-subpath) for more information.
+
+ ## Editor comments, suggestions, and performance
+
+ - **Comments and suggestions:** Leave threaded comments on any text in the [editor](/editor), reply, resolve, and @mention teammates with email notifications. Suggestion mode lets reviewers propose edits for authors to accept or reject.
+ - **Faster editor:** Improvements to initial load and navigation updates make the editor faster and more responsive.
+ - **Collapsible headings:** Collapse and expand sections under headings while editing to navigate long pages more easily.
+
+ ## Search filters and ranking
+
+ - **Search filters:** Add [filters to your docs search](/optimize/search) so readers can narrow results by product, version, or other categories.
+ - **Search boosting:** Per-page `boost` values set in frontmatter are now applied to search rankings, and search no longer promotes down-boosted pages via title matches.
+
+ ## Enterprise security and access control
+
+ - **Require SSO with break-glass access:** Enforce SSO sign-in for your entire organization, with designated break-glass members who can still sign in directly if your identity provider is unavailable. See [SSO](/dashboard/sso).
+ - **Network access IP allowlists:** Restrict dashboard access to trusted IP ranges with the new [network access](/dashboard/network-access) settings, and apply IP allowlists to external API keys for granular control.
+ - **Dashboard session lifetimes and revocation:** Configure how long dashboard sessions stay valid and revoke individual sessions from the members page, complementing the existing [SSO controls](/dashboard/sso).
+ - **Consolidated Identity & access page:** Manage SSO, SCIM, and network access settings on a single "Identity & access" page in the dashboard.
+
+ ## Assistant and automations
+
+ - **Clarifying questions:** The [assistant](/assistant) can now ask clarifying questions when a user's request is ambiguous. The assistant presents the questions as selectable option cards in chat.
+ - **Update from support feedback automation:** The new [Update from support feedback automation](/automations) reviews resolved support conversations from connected third-party apps and drafts documentation updates.
+ - **Contact form opt-out:** Turn off the assistant's in-chat contact form from [deflection settings](/assistant/configure) if you don't want the assistant to hand off to support.
+ - **Slack agent improvements:** The [Slack agent](/agent/slack) respects deploy-branch protection when choosing its review process, hides its review-process dropdown for Mintlify-hosted deployments, retries file fetches on upload races, and steers feedback reads to code mode.
+ - Retrying an assistant response now regenerates the answer instead of appending a duplicate turn, the assistant surfaces stream errors instead of failing silently, no longer shows stale content after navigation, and answers from the context it has gathered instead of returning an empty message when it reaches its tool call limit.
+ - Toggling an automation on or off no longer fails with a "workflow not found" error.
+
+ ## Other improvements
+
+ - **Schema.org JSON-LD on docs pages:** Pages now include auto-generated schema.org structured data to improve search-engine understanding of your content.
+ - **System theme:** Sites can now follow each reader's operating system light or dark mode preference with the new `system` theme option.
+ - **Granular PDF exports:** [Export PDFs](/optimize/pdf-exports) for specific pages or locales instead of the entire site.
+ - **Activity log deep links:** Rows in the usage activity log now link to the automation run or assistant conversation that generated the charge.
+ - **Prorated cost preview:** The billing page shows a prorated cost preview before you change credit tiers.
+ - **New localization codes:** Added support for the `zh-CN`, `zh-TW`, and `ja-JP` locale codes.
+ - **Custom OAuth redirect URIs for MCP:** Register your own allowed OAuth redirect URIs for your [MCP server](/ai/model-context-protocol) from the dashboard.
+ - **API playground:** Paste a JSON body into the [playground](/api-playground/overview) to auto-fill request body fields.
+ - **Support modal video attachments:** Attach `.mp4` recordings to support requests to give the team more context on issues.
+ - **Copy anchor URL from changelog:** Clicking the link icon on a changelog entry now copies the anchor URL to your clipboard.
+ - **Visitor GEO on `window.mintlify.geo`:** Client-side scripts can now read visitor country and region from `window.mintlify.geo` for personalization.
+
+ ## Bug fixes
+
+ - Nested `llms.txt` files no longer 404.
+ - End-user auth logout now performs a full-page navigation so state clears reliably.
+ - MCP discovery correctly reports OAuth 2.0 authentication on auth-enabled deployments.
+ - The billing page renders the plan for the current deployment instead of the organization default.
+ - PDF export links are normalized, and the table of contents no longer renders empty for certain deployments.
+ - Resolved accessibility violations in the `Card`, `Tabs`, and table components.
+ - Sites using OneTrust cookie consent now correctly stop analytics when a visitor revokes consent.
+
+
+
## Assistant skills and support handoff
@@ -220,7 +379,7 @@ noindex: true
- **Draft improvements from user feedback:** This new automation reviews recent [page feedback](/optimize/feedback) and opens pull requests based on what users report.
- The **update from code changes** automation (formerly sync content with code) defaults to run on a schedule rather than triggering on every code change. When it runs, the agent scans all code changes since the last run and opens one PR per related set of documentation updates. If a PR is still open from a previous automation run, new changes are appended to it rather than creating a new PR. This means a release worked on over several weeks produces a single docs PR to review instead of one per commit.
- - Automation titles and copy across the dashboard have been refreshed for clarity.
+ - Automation titles and copy across the dashboard updated for clarity.
## API playground
@@ -2248,4 +2407,4 @@ noindex: true
- Snippets V2: We now support fully reusable components and variables for snippets.
- Open source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome.
- AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears.
-
\ No newline at end of file
+
diff --git a/cli/commands.mdx b/cli/commands.mdx
index 1c7c515ef6..4525297e47 100644
--- a/cli/commands.mdx
+++ b/cli/commands.mdx
@@ -1,5 +1,6 @@
---
-title: "Commands"
+title: "Mintlify CLI command reference"
+sidebarTitle: "Commands"
description: "Complete reference for every Mintlify CLI command and flag, including mint dev, mint build, mint validate, mint broken-links, and more."
keywords: ["CLI", "mint", "commands", "flags", "reference"]
boost: 3
@@ -33,6 +34,45 @@ mint dev [flags]
---
+## `mint signup`
+
+Create a new Mintlify account from the terminal.
+
+```bash
+mint signup [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--firstName` | Your first name. |
+| `--lastName` | Your last name. |
+| `--company` | Your company name. |
+| `--email` | Email address for the account. |
+
+Run the command without flags to enter your details interactively. The CLI prompts for any value you do not pass as a flag.
+
+After you submit your details, Mintlify sends a verification link to your email. The command waits until you click the link, then creates your account, logs you in, and stores your credentials. When it finishes, open the [dashboard](https://app.mintlify.com) to connect your repository and start building.
+
+
+ `mint signup` does not return until you click the verification link, which can take several minutes. In scripts or automations, run it as a background process instead of waiting on it synchronously.
+
+
+### Examples
+
+```bash
+# Sign up interactively
+mint signup
+
+# Sign up with all details provided
+mint signup \
+ --firstName Jane \
+ --lastName Doe \
+ --company Acme \
+ --email jane@acme.com
+```
+
+---
+
## `mint login`
Authenticate with your Mintlify account.
@@ -67,6 +107,42 @@ mint status
---
+## `mint add-domain`
+
+Add a [custom domain](/customize/custom-domain) to your deployment from the terminal. Requires authentication with `mint login`.
+
+```bash
+mint add-domain
+```
+
+| Argument | Description |
+| --- | --- |
+| `domain` | The custom domain to add, like `docs.example.com`. Must be a bare hostname. |
+
+The command uses your configured subdomain from `mint config`. If you do not have a configured subdomain, it uses the first subdomain on your account.
+
+After registering the domain, the CLI waits up to 10 seconds for DNS records to generate, then prints the `TXT` and `CNAME` records to add at your domain provider:
+
+```text
+TXT _acme-challenge →
+TXT _cf-custom-hostname →
+CNAME @ → cname.mintlify.builders
+```
+
+Add the `TXT` records first, then add the `CNAME` once the verification records validate. See [Custom domain](/customize/custom-domain) for full DNS setup instructions, apex domain requirements, and TLS provisioning details.
+
+
+ If some `TXT` records are still generating when the command exits, check the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard for the remaining values.
+
+
+### Example
+
+```bash
+mint add-domain docs.example.com
+```
+
+---
+
## `mint automations`
Create, list, and delete [automations](/automations) from the terminal. Requires authentication with `mint login`.
@@ -201,11 +277,25 @@ The command scans `.mdx` and `.md` files for links and excludes files matching [
| Flag | Description |
| --- | --- |
+| `--files` | One or more file paths or globs to check. Defaults to the whole site. |
| `--check-anchors` | Also validate anchor links (for example, `/page#section`) against heading slugs. |
| `--check-external` | Also check external URLs for broken links. |
| `--check-redirects` | Also check that redirect destinations in `docs.json` resolve to valid paths. |
| `--check-snippets` | Also check links inside `` components. |
+Pass `--files` to limit the check to specific pages. This is useful for validating a single page you just edited or scoping checks to a directory in CI. When `--files` is set with `--check-external`, only external URLs on the selected pages are fetched.
+
+```bash
+# Check a specific page
+mint broken-links --files introduction.mdx
+
+# Check pages matching a glob
+mint broken-links --files "guides/**/*.mdx"
+
+# Pass multiple paths
+mint broken-links --files introduction.mdx "guides/**/*.mdx"
+```
+
---
## `mint a11y`
@@ -324,6 +414,65 @@ The overall score uses weighted scoring, so higher-impact checks contribute more
---
+## `mint deslop`
+
+Check documentation pages for AI-sounding prose and get rewrite suggestions. Requires authentication with `mint login`.
+
+```bash
+mint deslop [files...] [flags]
+```
+
+| Argument | Description |
+| --- | --- |
+| `files` | Optional. Paths or globs to check. If omitted, the command checks the `.md` and `.mdx` pages that changed in your working tree (Git diff plus untracked files). |
+
+| Flag | Description |
+| --- | --- |
+| `--format` | Output format: `table` (default, colored), `plain` (pipeable), or `json`. |
+| `--subdomain` | Documentation subdomain to check against. Defaults to your configured subdomain. |
+| `--threshold` | Fail a page when the sum of its AI-generated and AI-assisted fractions is greater than this value, from `0` to `1`. Defaults to `0.5`. |
+| `--fix-whitespace` | Normalize prose whitespace in the checked files (trailing spaces, blank-line runs, and invisible Unicode characters). Skips code blocks and frontmatter. |
+
+For each flagged page, the command reports the AI-written fraction, the specific passages that read as AI-generated with their line numbers, and suggested human-style rewrites.
+
+Each checked page consumes one AI credit. The command skips pages under 50 words and does not charge for them. If any page is at or above the threshold, or if a check returns an error, the command exits with code `1`. If every page is clean, the command exits with code `0`. This lets you run the command in a rewrite loop or in CI.
+
+### Examples
+
+```bash
+# Check pages changed in your working tree
+mint deslop
+
+# Check a specific page
+mint deslop docs/guide.mdx
+
+# Check every MDX page and emit JSON for scripting
+mint deslop "docs/**/*.mdx" --format json
+
+# Also clean up whitespace in the checked files
+mint deslop docs/guide.mdx --fix-whitespace
+```
+
+---
+
+## `mint format`
+
+Format every `.mdx` file in the current directory to Mintlify's canonical style. The command parses each file with the same MDX parser the web editor uses, then rewrites it in place if the canonical output differs.
+
+```bash
+mint format
+```
+
+Run the command from the root of your docs project. It walks every subdirectory, skipping paths matched by `.gitignore` and any Mintlify ignore rules. Files that already match the canonical output are left untouched.
+
+
+ `mint format` rewrites files in place. Commit or stash your changes before running it so you can review the diff.
+
+
+When it finishes, the command prints how many MDX files were reformatted and how many failed to parse. If any file fails, the command exits with code `1` and prints the file path and error, so you can run it in CI to enforce consistent formatting.
+
+---
+
## `mint new`
Create a new documentation project by picking a theme or cloning a pre-defined template from the [mintlify/templates](https://github.com/mintlify/templates) repository.
@@ -369,7 +518,6 @@ These commands are available to run but are not yet functional. Running them rec
| --- | --- |
| `mint ai` | AI-powered documentation tools. |
| `mint test` | Documentation testing. |
-| `mint signup` | Account sign-up from the CLI. |
| `mint mcp` | MCP server for documentation. |
---
diff --git a/cli/index.mdx b/cli/index.mdx
index 110d2cb90e..4666da9ad5 100644
--- a/cli/index.mdx
+++ b/cli/index.mdx
@@ -32,6 +32,12 @@ Run `mint broken-links` to find broken links, `mint a11y` to check accessibility
### Check agent readiness
Run `mint score` to evaluate how well agents can navigate a documentation site. With no arguments, the command scores your configured subdomain. Pass a URL to score any other site. The command displays an overall readiness score and individual check results.
+### Detect AI-sounding prose
+Run `mint deslop` to check pages for AI-generated prose and get human-style rewrite suggestions. With no arguments, the command checks the pages you have changed. It flags the specific passages that read as AI-generated so you can revise them.
+
+### Format MDX files
+Run `mint format` to rewrite the MDX files in your project to Mintlify's canonical style. The command walks every subdirectory and reformats files in place.
+
### Manage configuration
Run `mint config` to set persistent defaults like your documentation subdomain.
diff --git a/cli/install.mdx b/cli/install.mdx
index 85df56afaf..66f13b98cb 100644
--- a/cli/install.mdx
+++ b/cli/install.mdx
@@ -20,6 +20,23 @@ keywords: ["CLI", "npm", "install", "Node.js", "pnpm", "mint"]
```
+
+ Using an AI coding tool? Copy the following prompt to have your agent install the CLI and verify it works.
+
+
+{/* vale off */}
+
+
+Install the Mintlify CLI globally so I can preview my documentation locally.
+
+1. Confirm Node.js v20.17.0 or newer is installed by running `node --version`. If it is missing or older, tell me before continuing.
+2. Install the CLI with `npm i -g mint` (or `pnpm add -g mint` if I use pnpm).
+3. Verify the install by running `mint --version` and share the output.
+4. If the install fails with a permissions error, suggest re-running with `sudo` and explain the tradeoff.
+
+
+{/* vale on */}
+
## Create a new project
To create a new documentation project from the Mintlify starter template, run the following command:
@@ -28,6 +45,19 @@ To create a new documentation project from the Mintlify starter template, run th
mint new [directory]
```
+{/* vale off */}
+
+
+Create a new Mintlify project in the current workspace.
+
+1. Ask me for a project name and preferred theme (or template) if I haven't already told you.
+2. Run `mint new --name --theme ` non-interactively, substituting the values I gave you. If I chose a template instead, run `mint new --template `.
+3. After the command finishes, list the generated files and point out `docs.json` as the main configuration entry point.
+4. Run `mint dev` from the new directory and share the local preview URL.
+
+
+{/* vale on */}
+
If you do not specify a directory, the CLI prompts you to create a new subdirectory or overwrite the current directory.
diff --git a/components/cards.mdx b/components/cards.mdx
index f9d173771f..cf85c7acc9 100644
--- a/components/cards.mdx
+++ b/components/cards.mdx
@@ -77,7 +77,7 @@ You can customize the call-to-action text and control whether an arrow appears.
### Typed cards
-Add a `type` property to style a card with the same theme as a [callout](/components/callouts). Typed cards apply a colored background, border, and default icon that match the selected type, so you can use them to draw attention to grouped content like notes, warnings, or success states.
+Add a `type` property to style a card with the same theme as a [callout](/components/callouts). Typed cards apply a colored background, border, and default icon that match the selected type. Use them to draw attention to grouped content like notes, warnings, or success states.
Supported types: `info`, `warning`, `note`, `tip`, `check`, and `danger`. Optionally, override the default icon with the `icon` property.
diff --git a/components/icons.mdx b/components/icons.mdx
index 9421adb1eb..4e1d450d2b 100644
--- a/components/icons.mdx
+++ b/components/icons.mdx
@@ -15,6 +15,16 @@ Use icons from Font Awesome, Lucide, Tabler, SVGs, external URLs, or files in yo
` and `` are aliases, so either tag works with either syntax.
+
+Use the Markdown list syntax for quick, static trees where every folder can expand by default. Use the component syntax when you need to control open state per folder with `defaultOpen`, mark folders as non-interactive with `openable`, or mix files and folders at arbitrary depth.
+
+## Markdown list syntax
+
+Write a nested Markdown list inside `` (or ``) to describe a folder structure. Add a trailing slash to mark a folder, or nest items under it. Folders that contain nested items expand by default.
+
+
+
+- docs/
+ - index.mdx
+ - guides/
+ - configuration.mdx
+- docs.config.ts
+
+
+
+````mdx File tree example
+
+
+- docs/
+ - index.mdx
+ - guides/
+ - configuration.mdx
+- docs.config.ts
+
+
+````
+
+Leave a blank line after the opening tag and before the closing tag so that the list parses as Markdown. Names strip inline formatting like `` `code` ``, `**bold**`, or `_italic_`.
+
## Basic tree
diff --git a/components/update.mdx b/components/update.mdx
index 57d13e14a0..4edcdd835e 100644
--- a/components/update.mdx
+++ b/components/update.mdx
@@ -63,7 +63,7 @@ If your update includes components or HTML, use the `rss` prop to provide altern
## Props
- Label for the update. Appears to the left of the update and creates an anchor link. Labels should be unique.
+ Label for the update. Appears to the left of the update and creates an anchor link using the same [automatic anchor ID rules](/create/text#automatic-anchor-ids) as headings. Use unique labels to create distinct anchor links.
diff --git a/contact-support.mdx b/contact-support.mdx
index 71563eb96d..ecd1db1e27 100644
--- a/contact-support.mdx
+++ b/contact-support.mdx
@@ -13,11 +13,10 @@ Visit our [YouTube](https://www.youtube.com/@GetMintlify/videos) channel for tut
## Message support
-Send us a message from your [dashboard](https://app.mintlify.com/). Click **Support** in the sidebar.
+Send us a message from your [dashboard](https://app.mintlify.com/). Click the 
- 
+ 
diff --git a/create/changelogs.mdx b/create/changelogs.mdx
index 3f33dbd8bc..3e9543c9a4 100644
--- a/create/changelogs.mdx
+++ b/create/changelogs.mdx
@@ -66,6 +66,8 @@ Add `tags` to your `Update` components to replace the table of contents with tag
When a user selects multiple tags, the changelog shows only updates that include every selected tag. The changelog hides updates without tags whenever a filter is active.
+Selected tags are reflected in the page URL as a `?tags=` query parameter, so users can share deep links to a filtered view of the changelog. Opening a link like `/changelog?tags=Spearmint` activates matching sidebar filters on load, and updating filters keeps the URL in sync. Separate multiple tags with commas, for example `/changelog?tags=Spearmint,Peppermint`.
+
```mdx Tag filters example wrap
Added a new Wintergreen flavor.
diff --git a/create/reusable-snippets.mdx b/create/reusable-snippets.mdx
index f3c5e93946..7218f8ceae 100644
--- a/create/reusable-snippets.mdx
+++ b/create/reusable-snippets.mdx
@@ -4,7 +4,7 @@ description: "Create reusable content snippets with variables to maintain consis
keywords: ["content snippets", "reusable content", "variables"]
---
-One of the core principles of software development is DRY (Don't Repeat Yourself), which applies to documentation too. If you find yourself repeating the same content in multiple places, create a custom snippet for that content. Snippets contain content that you can import into other files to reuse. You control where the snippet appears on a page. If you ever need to update the content, you only need to edit the snippet rather than every file where the snippet is used.
+One of the core principles of software development is DRY (Don't Repeat Yourself), which applies to documentation too. If you find yourself repeating the same content in multiple places, create a custom snippet for that content. Snippets contain content that you can import into other files to reuse. You control where the snippet appears on a page. If you ever need to update the content, you only need to edit the snippet rather than every file where the snippet appears.
Snippets are not currently supported in the web editor. To use snippets, edit your MDX files locally with the CLI or push snippet imports directly to your repository.
@@ -18,7 +18,7 @@ When you import a snippet into another file, the snippet only appears where you
## Create snippets
-Create a file with the content you want to reuse. Snippets can contain all content types supported by Mintlify and they can import other snippets.
+Create a file with the content you want to reuse. Snippets can contain all content types supported by Mintlify and they can import other snippets. See [Nested snippets](#nested-snippets) for where to declare imports when nesting.
## Import snippets into pages
@@ -27,19 +27,24 @@ Import snippets into pages using either an absolute or relative path.
- **Absolute imports**: Start with `/` for imports from the root of your project.
- **Relative imports**: Use `./` or `../` to import snippets relative to the current file's location.
+The name you use to render an imported snippet as a JSX tag must start with an uppercase letter, such as `MySnippet`. MDX treats lowercase tags such as `
Relative imports enable IDE navigation. Press CMD and click a snippet name in your editor to jump directly to the snippet definition.
### Import text
-1. Add content to your snippet file that you want to reuse.
+
+
+ Add the content you want to reuse.
```mdx shared/my-snippet.mdx wrap
Hello world! This is my content I want to reuse across pages.
```
-
-2. Import the snippet into your destination file using either an absolute or relative path.
+
+
+ Use either an absolute or relative path.
@@ -70,13 +75,49 @@ Import snippets into pages using either an absolute or relative path.
```
+
+
+
+### Nested snippets
+
+Snippets can import other snippets. Declare the import in the snippet file that uses the nested snippet, not in the page that imports the parent snippet.
+
+Each file resolves its own imports. Imports declared on a page do not apply to the snippets that the page imports. A nested snippet that relies on a page-level import may render as empty content.
+
+
+
+ Declare the import where you want to use the nested snippet.
+
+ ```mdx shared/parent-snippet.mdx
+ import ChildSnippet from "/shared/child-snippet.mdx";
+
+ This snippet renders another snippet beneath this sentence.
+
+
+
+ You do not need to import the nested snippet.
+
+ ```mdx destination-file.mdx
+ ---
+ title: "An example page"
+ description: "This is an example page that imports a snippet containing a nested snippet."
+ ---
+
+ import ParentSnippet from "/shared/parent-snippet.mdx";
+
+
+
### Import variables
Reference variables from a snippet in a page.
-1. Export variables from a snippet file.
-
+
+
```mdx shared/custom-variables.mdx
export const myName = "Ronan";
@@ -84,9 +125,8 @@ Reference variables from a snippet in a page.
;
```
-
-2. Import the snippet from your destination file and use the variable.
-
+
+
```mdx destination-file.mdx
---
title: "An example page"
@@ -97,18 +137,23 @@ Reference variables from a snippet in a page.
Hello, my name is {myName} and I like {myObject.fruit}.
```
+
+
### Import snippets with variables
Use variables to pass data to a snippet when you import it.
-1. Add variables to your snippet and pass in properties when you import it. In this example, the variable is `{word}`.
+
+
+ Pass in properties when you import it. In this example, the variable is `{word}`.
```mdx shared/my-snippet.mdx
My keyword of the day is {word}.
```
-
-2. Import the snippet into your destination file with the variable. The passed property replaces the variable in the snippet definition.
+
+
+ The passed property replaces the variable in the snippet definition.
```mdx destination-file.mdx
---
@@ -120,6 +165,8 @@ Use variables to pass data to a snippet when you import it.
+
Variables also interpolate inside fenced code blocks. This is useful for snippets that include installation commands or other code examples that differ by package name, version, or environment.
@@ -141,7 +188,9 @@ import InstallSnippet from "/shared/install-snippet.mdx";
### Import React components
-1. Create a snippet with a JSX component. See [React components](/customize/react-components) for more information.
+
+
+ See [React components](/customize/react-components) for more information.
```js components/my-jsx-snippet.jsx
export const MyJSXSnippet = () => {
@@ -153,12 +202,11 @@ import InstallSnippet from "/shared/install-snippet.mdx";
};
```
-
- When creating JSX snippets, use arrow function syntax (`=>`) rather than function declarations. The `function` keyword is not supported in snippets.
-
-
-2. Import the snippet.
-
+
+ When creating JSX snippets, use arrow function syntax (`=>`) rather than function declarations. The `function` keyword is not supported in snippets.
+
+
+
```mdx destination-file.mdx
---
title: "An example page"
@@ -169,3 +217,5 @@ import InstallSnippet from "/shared/install-snippet.mdx";
+
diff --git a/create/text.mdx b/create/text.mdx
index 63e88b1642..ac657ceb83 100644
--- a/create/text.mdx
+++ b/create/text.mdx
@@ -24,9 +24,38 @@ Use `##` (H2) through `######` (H6) for content sections. The title set in a pag
Use descriptive, keyword-rich headings that clearly indicate the content that follows. This improves both user navigation and search engine optimization.
+### Automatic anchor IDs
+
+By default, Mintlify generates an anchor ID from the heading text. Generated IDs use the following rules:
+
+- Mintlify converts letters to lowercase and whitespace to hyphens.
+- Mintlify converts straight apostrophes to right single quotation marks (`’`) and keeps them in the ID.
+- Mintlify converts periods to hyphens and removes parentheses.
+- Mintlify converts capital letters within a word to lowercase without adding hyphens.
+- Mintlify preserves slashes and ampersands.
+
+When a page has multiple headings that generate the same ID, Mintlify adds `-2`, `-3`, and so on. The counter applies across the entire page, including headings nested inside components such as tabs.
+
+The following examples show how heading text maps to a generated anchor ID:
+
+| Heading text | Generated ID |
+| :--- | :--- |
+| `Getting started` | `getting-started` |
+| `Config.json options` | `config-json-options` |
+| `What's new` | `what’s-new` |
+| `Rate limits (per minute)` | `rate-limits-per-minute` |
+| `Read/write access` | `read/write-access` |
+| `Fees & billing` | `fees-&-billing` |
+| `OAuth` | `oauth` |
+| Duplicate `Overview` heading | `overview-2` |
+
+
+ Mintlify's anchor IDs do not use GitHub-style slugging. Percent-encode non-ASCII characters when constructing a URL programmatically.
+
+
### Custom heading IDs
-By default, Mintlify generates anchor IDs automatically from heading text. You can override the generated ID with a custom one using the `{#custom-id}` syntax:
+To override the generated ID with a custom one, use the `{#custom-id}` syntax.
```mdx
## My section {#my-custom-anchor}
diff --git a/credits.mdx b/credits.mdx
index 4c6b9c9c69..8c043dbc7f 100644
--- a/credits.mdx
+++ b/credits.mdx
@@ -14,9 +14,9 @@ For the most current pricing information, see the [Pricing page](https://mintlif
## Plan availability
-Credits are available on the **Pro plan and above**. Every Pro plan includes 10,000 credits per month, and you can purchase additional credits from the [Usage](https://app.mintlify.com/settings/organization/usage) page whenever you need more.
+Credits are available on the **Pro and Enterprise plans**. Every Pro plan includes 10,000 credits per month, and you can purchase additional credits from the [Usage](https://app.mintlify.com/settings/organization/usage) page whenever you need more.
-The free Starter plan does not include AI features. You cannot purchase credits on the starter plan. To use the assistant, agent, or automations, upgrade to Pro or Enterprise.
+The free Starter plan does not include AI features. You cannot purchase credits on the Starter plan. To use the assistant, agent, or automations, upgrade to Pro or Enterprise.
Customers on legacy credit plans keep their existing credit packs and pricing. The tiers below apply to the Pro plan.
diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx
index eb5c05a2dd..fad503aae5 100644
--- a/customize/custom-domain.mdx
+++ b/customize/custom-domain.mdx
@@ -1,71 +1,93 @@
---
title: "Custom domain"
-description: "Host your documentation on a custom domain with DNS configuration, automatic TLS certificates, and subdomain or subpath routing options."
-keywords: ["custom domain setup", "DNS configuration", "CNAME records", "TLS certificates"]
+description: "Host your site at your own domain, subdomain, or subpath with DNS records, automatic TLS certificates, and Mintlify-managed or proxy traffic routing."
+keywords: ["custom domain setup", "DNS configuration", "CNAME records", "TLS certificates", "subpath", "hosting", "base path", "apex domain", "CNAME flattening", "ALIAS records"]
---
+Host your documentation at your own domain, like `docs.example.com`, or at a subpath on your domain, like `example.com/docs`.
+
To host your documentation on a custom domain:
+
1. Add your domain in your dashboard.
2. Configure DNS settings on your domain provider.
3. Allow time for DNS to propagate and TLS certificates to be automatically provisioned.
-
- Looking to set up a subpath like `example.com/docs`? See [/docs subpath](/deploy/docs-subpath).
-
+## Choose where to host your documentation
+
+You can host your documentation at the root of a domain, a subdomain, or a subpath.
+
+**Domain or subdomain**: Host your documentation at a domain like `example.com` or a subdomain like `docs.example.com`. Mintlify serves all traffic for the domain or subdomain. Hosting at a domain with no subdomain requires a DNS provider that supports CNAME flattening or `ALIAS` records. See [Apex domains](#apex-domains).
+
+**Subpath**: Host your documentation at a path on your domain, like `example.com/docs`. Enable the **Host at** toggle when you add your domain and enter your base path. How traffic reaches Mintlify depends on your DNS:
+- If your domain's DNS points to Mintlify, Mintlify serves your documentation at your subpath. Only point your domain at Mintlify if it hosts no other content and Mintlify can receive all paths on the domain.
+- If another site runs on your domain, your app or CDN keeps receiving traffic for the domain and proxies only your subpath to Mintlify.
+
+
+ Subpath hosting is not supported for documentation with [authentication](/deploy/authentication-setup) enabled.
+
## Add your custom domain
1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
-2. Enter your domain name. For example, `docs.example.com` or `www.example.com`.
-3. Click **Add domain**.
-
-
- 
- 
-
+2. To host at a subpath, enable the **Host at** toggle and enter your base path, like `/docs`.
+3. Enter your domain name. For example, `docs.example.com` or `example.com`.
+4. Click **Add domain**.
-## Configure your DNS
+If your domain traffic routes to Mintlify, the dashboard displays the DNS records to add at your domain provider.
-1. On your domain provider's website, navigate to your domain's DNS settings.
-2. Create a new DNS record with the following values:
-
-```text
-CNAME | docs | cname.mintlify.builders
-```
+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.
- Each domain provider has different ways to add DNS records. Refer to your domain provider's documentation for specific instructions.
+ 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 deployment and prints the DNS records to configure.
-
- Do not add or change your `CNAME` until both verification `TXT` records show as verified in your dashboard. Each appears with a green check when DNS is correct. The dashboard verifies `TXT` records before certificate provisioning can complete. Switching `CNAME` too early commonly breaks HTTPS until provisioning finishes.
+### Base path requirements
- If you migrate an existing domain and want zero downtime, publish the verification `TXT` records first and wait until they show verified and TLS has pre-provisioned before pointing `CNAME` at Mintlify.
+Your base path can be any path that meets these requirements:
- This pre-validation flow does not work for domains proxied through Cloudflare. See [Cloudflare-proxied domains](#cloudflare-proxied-domains).
-
+- Starts with `/` and contains no spaces, query strings, or hashes.
+- Is at most 128 characters.
+- Is not a path that Mintlify reserves: `/_next`, `/_mintlify`, `/_sites`, `/_live-preview`, `/api`, `/login`, `/logout`, `/mcp`, `/feedback`, `/openapi-specs.download`, `/llms.txt`, `/llms-full.txt`, `/sitemap.xml`, `/robots.txt`, `/skill.md`, and `/.well-known`.
+
+### Change your base path
-### Verification TXT records
+When you change your base path or subpath, Mintlify rebuilds and redeploys your site. Your site stays live at the current path until the deployment finishes, then traffic switches to the new path. If the deployment fails, your site continues serving from the current path and you can retry the change from your dashboard.
-After you add a custom domain, the dashboard displays two `TXT` records that you must add at your DNS provider:
+## Configure your DNS
+
+
+ Each domain provider has different ways to add DNS records. Refer to your domain provider's documentation for specific instructions.
+
+
+1. On your domain provider's website, navigate to your domain's DNS settings.
+2. Create the DNS records shown in your dashboard.
+
+The dashboard displays verification `TXT` records and a `CNAME` record:
```text
TXT | _acme-challenge. |
TXT | _cf-custom-hostname. |
+CNAME | | cname.mintlify.builders
```
The `_acme-challenge` record authorizes Let's Encrypt to issue a TLS certificate for your domain, and the `_cf-custom-hostname` record verifies that you control the domain.
+
+ Add your `TXT` records first. Do not add or change your `CNAME` until both verification `TXT` records show as verified in your dashboard. Each appears with a green check when DNS is correct. The dashboard verifies `TXT` records before certificate provisioning can complete. Switching `CNAME` too early commonly breaks HTTPS until provisioning finishes.
+
+ If you migrate an existing domain and want zero downtime, publish the verification `TXT` records first and wait until they show verified and TLS has pre-provisioned before pointing `CNAME` at Mintlify.
+
+ This pre-validation flow does not work for domains proxied through Cloudflare. See [Cloudflare-proxied domains](#cloudflare-proxied-domains).
+
+
The dashboard polls DNS in the background and marks each record with a green check once it verifies the expected value. After saving records at your DNS provider, allow a short time for propagation before status updates appear.
+### Apex domains
+
+If you host your documentation at an apex domain like `example.com` with no subdomain, your DNS provider must support CNAME flattening or a virtual record type like `ALIAS` or `ANAME`. Standard DNS does not allow a `CNAME` record at the apex of a domain, so providers without this support cannot create the record shown in your dashboard.
+
+Providers that support apex `CNAME` records include Cloudflare (CNAME flattening), Amazon Route 53 (alias records), DNSimple (`ALIAS` records), and Porkbun (`ALIAS` records). If your provider does not support any of these, host your documentation at a subdomain like `docs.example.com` instead.
+
### DNS propagation
DNS changes typically take 1-24 hours to propagate globally, though it can take up to 48 hours in some cases. Use a tool like [DNSChecker](https://dnschecker.org) to verify your DNS configuration is correct.
@@ -110,7 +132,7 @@ If you need zero downtime during migration, set the `CNAME` record's proxy statu
### Retry validation
-If your domain is still pending validation after adding the verification `TXT` record, you can retry validation manually from your dashboard.
+`TXT` records typically validate within five minutes. If your domain is still pending validation after adding the verification `TXT` records, manually retry validation from your dashboard.
1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
2. Find your pending custom domain.
@@ -118,6 +140,10 @@ 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.
+## Remove a custom domain
+
+To remove a custom domain, click the
+
+```
+
+Props:
+- `caption` (string): Text below image. Supports Markdown.
+- `hint` (string): Text above image.
+
+## Icons
+
+Display icons inline.
+
+```mdx
+
+
+
+ {count}
+
+
+ );
+};
+```
+
+Import in any page using the root-relative path to the file:
+
+```mdx
+import { Counter } from "/snippets/counter.jsx";
+
+
-
-
-3. Follow the Slack prompts to install the `mintlify` app in your workspace and grant the requested permissions.
-4. Confirm the connection in your Mintlify dashboard to your Slack workspace.
-5. Test that the agent is working and responds when you:
- - Send a direct message to the agent.
- - Mention the agent with `@mintlify` in a channel.
-
-
+
-
-
+2. To host at a subpath, enable the **Host at** toggle and enter your base path, like `/docs`.
+3. Enter your domain name. For example, `docs.example.com` or `example.com`.
+4. Click **Add domain**.
-## Configure your DNS
+If your domain traffic routes to Mintlify, the dashboard displays the DNS records to add at your domain provider.
-1. On your domain provider's website, navigate to your domain's DNS settings.
-2. Create a new DNS record with the following values:
-
-```text
-CNAME | docs | cname.mintlify.builders
-```
+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.