From 4dadb8d675c9b396fbcef0c51cbd749298009800 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 25 Jun 2026 21:18:27 +0000
Subject: [PATCH] docs: translate missing pages into es, fr, zh
---
es.json | 3 +-
es/deploy/gitlab-self-hosted.mdx | 122 ++++++++++++++
fr.json | 3 +-
fr/deploy/gitlab-self-hosted.mdx | 122 ++++++++++++++
zh.json | 3 +-
zh/agent/integrations.mdx | 73 ++++++++
zh/ai/mintlify-mcp.mdx | 185 ++++++++++++++++++++
zh/credits.mdx | 85 ++++++++++
zh/deploy/gitlab-self-hosted.mdx | 122 ++++++++++++++
zh/editor/agent.mdx | 126 ++++++++++++++
zh/editor/branching-and-publishing.mdx | 224 +++++++++++++++++++++++++
zh/editor/tutorial.mdx | 70 ++++++++
zh/optimize/search.mdx | 93 ++++++++++
13 files changed, 1228 insertions(+), 3 deletions(-)
create mode 100644 es/deploy/gitlab-self-hosted.mdx
create mode 100644 fr/deploy/gitlab-self-hosted.mdx
create mode 100644 zh/agent/integrations.mdx
create mode 100644 zh/ai/mintlify-mcp.mdx
create mode 100644 zh/credits.mdx
create mode 100644 zh/deploy/gitlab-self-hosted.mdx
create mode 100644 zh/editor/agent.mdx
create mode 100644 zh/editor/branching-and-publishing.mdx
create mode 100644 zh/editor/tutorial.mdx
create mode 100644 zh/optimize/search.mdx
diff --git a/es.json b/es.json
index bc72df3bd4..1a8bb790a0 100644
--- a/es.json
+++ b/es.json
@@ -190,7 +190,8 @@
"es/deploy/ci",
"es/deploy/github",
"es/deploy/ghes",
- "es/deploy/gitlab"
+ "es/deploy/gitlab",
+ "es/deploy/gitlab-self-hosted"
]
},
{
diff --git a/es/deploy/gitlab-self-hosted.mdx b/es/deploy/gitlab-self-hosted.mdx
new file mode 100644
index 0000000000..6b0ff9e0c3
--- /dev/null
+++ b/es/deploy/gitlab-self-hosted.mdx
@@ -0,0 +1,122 @@
+---
+title: "OAuth de GitLab autoalojado"
+description: "Conecta una instancia autoalojada de GitLab con Mintlify mediante OAuth para que las automatizaciones puedan clonar repositorios, enviar commits y abrir merge requests en tu nombre."
+keywords: ["GitLab", "autoalojado", "OAuth", "automatizaciones", "enterprise"]
+---
+
+Mintlify admite la autorización basada en OAuth para instancias autoalojadas de GitLab, además de gitlab.com. OAuth permite que el agente de Mintlify actúe como un usuario de GitLab durante las ejecuciones de automatización: clonar repositorios, enviar commits, abrir merge requests y registrar webhooks de proyectos.
+
+Debes configurar la autorización OAuth para las instancias autoalojadas de GitLab a fin de habilitar [automatizaciones](/es/automations).
+
+A diferencia de gitlab.com, donde Mintlify proporciona una única aplicación OAuth contra la que se autoriza cada cliente, cada instancia autoalojada debe registrar su propia aplicación OAuth. Crea la aplicación en tu instancia de GitLab, comparte sus credenciales con Mintlify y, a continuación, completa una autorización OAuth para conectar un usuario.
+
+
+ Esta guía abarca únicamente la integración **OAuth** que impulsa las automatizaciones. Debes configurar por separado la conexión del lado del despliegue (utilizada para la sincronización de contenido y las vistas previas) con un deploy token; consulta la [guía de GitLab](/es/deploy/gitlab). La integración de OAuth depende de la conexión del lado del despliegue.
+
+
+
+ ## Requisitos previos
+
+
+- Acceso de administrador a tu instancia autoalojada de GitLab.
+- Tu instancia de GitLab debe ser accesible desde `https://app.mintlify.com`. Las instancias detrás de una VPN o de un firewall que bloquee la entrada pública no funcionan.
+- Una organización de Mintlify que tenga habilitada la función de GitLab autoalojado. Contacta con soporte si no ves la sección **Self-hosted GitLab** en la página del dashboard [Git settings](https://app.mintlify.com/settings/deployment/git-settings).
+
+
+ ## Configura la conexión
+
+
+
+
+ En tu GitLab autoalojado, inicia sesión como administrador y ve a **Admin Area** \> **Applications** \> **Add new application**.
+
+ Configura la aplicación con estos valores:
+
+ - **Name**: `Mintlify`
+ - **Redirect URI**: `https://app.mintlify.com/api/gitlab-oauth/callback`
+ - **Trusted**: déjalo **sin marcar**. Marcar la aplicación como confiable omite la pantalla de consentimiento para todos los usuarios; dejarlo sin marcar muestra un mensaje de autorización normal la primera vez que cada usuario se conecta.
+ - **Confidential**: **marcado**. Mintlify es un cliente del lado del servidor y mantiene el secreto confidencial.
+ - **Scopes**: selecciona `api`, `read_repository` y `write_repository`. El agente los usa para leer metadatos de proyectos, clonar repositorios y enviar commits.
+
+ Haz clic en **Save application**.
+
+
+ Editar una aplicación OAuth en GitLab puede rotar el client secret de manera silenciosa. Si haces cambios más adelante, haz clic en **Renew secret** y actualiza el nuevo valor en Mintlify.
+
+
+
+ Después de guardar, GitLab muestra el **Application ID** y el **Secret** de la aplicación. Mantén esta página abierta: el secreto solo se muestra una vez.
+
+
+ En tu dashboard de Mintlify, abre **Settings** \> **Git settings** y busca la sección **Self-hosted GitLab** dentro de **GitLab OAuth**.
+
+ Haz clic en **Connect Self-Hosted GitLab** e introduce:
+
+ - **GitLab instance URL**: la URL pública de tu instancia de GitLab, por ejemplo `https://gitlab.your-company.com`. Mintlify se comunica con tu instancia a través de esta URL al intercambiar tokens y llamar a la API de GitLab.
+ - **OAuth application client ID**: el **Application ID** del paso anterior.
+ - **OAuth application client secret**: el **Secret** del paso anterior.
+
+ Haz clic en **Save instance**. Mintlify cifra el secreto en reposo y nunca lo devuelve al navegador después de guardarlo.
+
+
+ Haz clic en **Authorize self-hosted GitLab**. Serás redirigido a tu instancia de GitLab, se te pedirá que inicies sesión si es necesario y verás una pantalla de consentimiento con los scopes solicitados.
+
+ Después de hacer clic en **Authorize** en GitLab, volverás a Mintlify y la nueva conexión aparecerá en la lista de instalaciones, con una insignia que muestra el nombre de host de tu instancia.
+
+
+ Expande la conexión en el dashboard. Mintlify lista todos los grupos a los que el usuario que autoriza tiene acceso como Maintainer o superior, además de una entrada **Personal projects** para los proyectos en el namespace personal del usuario.
+
+ Marca la casilla junto a cada proyecto que deba participar en las automatizaciones. Mintlify registra un webhook en el proyecto, genera un secret token y lo almacena cifrado. A partir de ese momento, Mintlify recibe eventos de push y merge-request de tu instancia para ese proyecto.
+
+
+ El usuario que se conecta debe tener el rol **Maintainer** en un proyecto para que Mintlify pueda emitir project access tokens de corta duración durante las ejecuciones de automatización. Sin Maintainer, el agente puede leer pero no puede enviar commits ni abrir merge requests.
+
+
+
+
+
+ ## Rotar credenciales
+
+
+Si necesitas cambiar el client secret de la aplicación registrada —por ejemplo, después de renovarlo en GitLab—, elimina la instancia guardada en Mintlify y vuelve a añadirla con los nuevos valores. Primero debes revocar las conexiones OAuth activas; de lo contrario, Mintlify bloqueará la eliminación.
+
+
+
+ Haz clic en **Revoke** en cada instalación listada bajo la instancia autoalojada. Esto elimina el webhook en cada proyecto conectado y revoca el token OAuth en GitLab.
+
+
+ En la tarjeta **Self-hosted GitLab**, haz clic en **Remove instance**.
+
+
+ Sigue los pasos de **Set up the connection** descritos anteriormente con el nuevo client secret.
+
+
+
+
+ ## Resolución de problemas
+
+
+
+ ### `invalid_client` después de autorizar
+
+
+GitLab rechazó el paso de intercambio de tokens porque el client secret que envió Mintlify no coincide con el registrado en la aplicación. La causa más habitual es que el secreto se rotó en GitLab —por una acción explícita de **Renew secret**, o de forma silenciosa cuando alguien editó la aplicación— y el valor en Mintlify está obsoleto.
+
+Solución: rota las credenciales siguiendo los pasos de [Rotar credenciales](#rotate-credentials) con el secreto actual.
+
+
+ ### El registro del webhook falló: `Invalid url given`
+
+
+GitLab se negó a registrar el webhook porque la URL que envió Mintlify (`https://app.mintlify.com/gitlab-oauth-webhook`) fue rechazada por la lista de permitidos de solicitudes salientes de GitLab. Las instancias autoalojadas rechazan las URLs "locales" a menos que el administrador las permita explícitamente.
+
+Solución: en el área de administración de GitLab, ve a **Settings** \> **Network** \> **Outbound requests** y activa **Allow requests to the local network from webhooks and integrations**. Si tu política de red bloquea `app.mintlify.com`, contacta con tu administrador de red para permitir HTTPS saliente hacia ese host.
+
+
+ ### No aparece pantalla de consentimiento al autorizar
+
+
+Si no ves el cuadro de diálogo de consentimiento de GitLab al autorizar, puede deberse a una de estas causas:
+
+- La aplicación está marcada como **Trusted** en GitLab. Las aplicaciones marcadas como confiables omiten el consentimiento para todos los usuarios. Desmarca **Trusted** en la configuración de la aplicación si quieres que los usuarios vean y confirmen los scopes.
+- Tu usuario de GitLab ha autorizado previamente la aplicación con los mismos scopes. GitLab recuerda las concesiones anteriores y omite el consentimiento en autorizaciones posteriores. Revoca la autorización de la aplicación en **User settings** \> **Applications** \> **Authorized applications** para volver a ver el consentimiento.
diff --git a/fr.json b/fr.json
index 62b58ed14e..21ce49c96d 100644
--- a/fr.json
+++ b/fr.json
@@ -190,7 +190,8 @@
"fr/deploy/ci",
"fr/deploy/github",
"fr/deploy/ghes",
- "fr/deploy/gitlab"
+ "fr/deploy/gitlab",
+ "fr/deploy/gitlab-self-hosted"
]
},
{
diff --git a/fr/deploy/gitlab-self-hosted.mdx b/fr/deploy/gitlab-self-hosted.mdx
new file mode 100644
index 0000000000..a81960f426
--- /dev/null
+++ b/fr/deploy/gitlab-self-hosted.mdx
@@ -0,0 +1,122 @@
+---
+title: "OAuth GitLab auto-hébergé"
+description: "Connectez une instance GitLab auto-hébergée à Mintlify via OAuth pour que les automatisations puissent cloner des référentiels, pousser des commits et ouvrir des merge requests en votre nom."
+keywords: ["GitLab", "auto-hébergé", "OAuth", "automatisations", "entreprise"]
+---
+
+Mintlify prend en charge l'autorisation basée sur OAuth pour les instances GitLab auto-hébergées, en plus de gitlab.com. OAuth permet à l'agent Mintlify d'agir comme un utilisateur GitLab pendant les exécutions d'automatisation : cloner des référentiels, pousser des commits, ouvrir des merge requests et enregistrer des webhooks de projet.
+
+Vous devez configurer l'autorisation OAuth pour les instances GitLab auto-hébergées afin de prendre en charge les [automatisations](/fr/automations).
+
+Contrairement à gitlab.com, où Mintlify fournit une seule application OAuth contre laquelle chaque client s'autorise, chaque instance auto-hébergée doit enregistrer sa propre application OAuth. Créez l'application sur votre instance GitLab, partagez ses identifiants avec Mintlify, puis effectuez une autorisation OAuth pour connecter un utilisateur.
+
+
+ Ce guide concerne uniquement l'intégration **OAuth** qui alimente les automatisations. Vous devez configurer la connexion côté déploiement (utilisée pour la synchronisation du contenu et les prévisualisations) séparément avec un jeton de déploiement, voir le [guide GitLab](/fr/deploy/gitlab). L'intégration OAuth dépend de la connexion côté déploiement.
+
+
+
+ ## Prérequis
+
+
+- Accès administrateur à votre instance GitLab auto-hébergée.
+- Votre instance GitLab doit être accessible depuis `https://app.mintlify.com`. Les instances derrière un VPN ou derrière un pare-feu qui bloque l'entrée publique ne fonctionnent pas.
+- Une organisation Mintlify pour laquelle la fonctionnalité GitLab auto-hébergé est activée. Contactez le support si vous ne voyez pas la section **Self-hosted GitLab** dans la page de votre tableau de bord [Git settings](https://app.mintlify.com/settings/deployment/git-settings).
+
+
+ ## Configurer la connexion
+
+
+
+
+ Dans votre GitLab auto-hébergé, connectez-vous en tant qu'administrateur et accédez à **Admin Area** \> **Applications** \> **Add new application**.
+
+ Configurez l'application avec ces valeurs :
+
+ - **Name** : `Mintlify`
+ - **Redirect URI** : `https://app.mintlify.com/api/gitlab-oauth/callback`
+ - **Trusted** : laissez **décoché**. Marquer l'application comme approuvée saute l'écran de consentement pour chaque utilisateur ; le laisser décoché affiche une invite d'autorisation normale la première fois que chaque utilisateur se connecte.
+ - **Confidential** : **coché**. Mintlify est un client côté serveur et garde le secret confidentiel.
+ - **Scopes** : sélectionnez `api`, `read_repository` et `write_repository`. L'agent les utilise pour lire les métadonnées du projet, cloner des référentiels et pousser des commits.
+
+ Cliquez sur **Save application**.
+
+
+ Modifier une application OAuth sur GitLab peut faire tourner le secret client silencieusement. Si vous apportez des modifications par la suite, cliquez sur **Renew secret** et mettez à jour la nouvelle valeur dans Mintlify.
+
+
+
+ Après l'enregistrement, GitLab affiche l'**Application ID** et le **Secret** de l'application. Gardez cette page ouverte — le secret n'est affiché qu'une seule fois.
+
+
+ Dans votre tableau de bord Mintlify, ouvrez **Settings** \> **Git settings** et trouvez la section **Self-hosted GitLab** sous **GitLab OAuth**.
+
+ Cliquez sur **Connect Self-Hosted GitLab** et saisissez :
+
+ - **GitLab instance URL** : l'URL publique de votre instance GitLab, par exemple `https://gitlab.your-company.com`. Mintlify accède à votre instance via cette URL lors de l'échange de jetons et des appels à l'API GitLab.
+ - **OAuth application client ID** : l'**Application ID** de l'étape précédente.
+ - **OAuth application client secret** : le **Secret** de l'étape précédente.
+
+ Cliquez sur **Save instance**. Mintlify chiffre le secret au repos et ne le renvoie jamais au navigateur après l'enregistrement.
+
+
+ Cliquez sur **Authorize self-hosted GitLab**. Vous serez redirigé vers votre instance GitLab, invité à vous connecter si nécessaire, et un écran de consentement listant les portées demandées s'affichera.
+
+ Après avoir cliqué sur **Authorize** sur GitLab, vous serez redirigé vers Mintlify et la nouvelle connexion apparaîtra dans la liste des installations, étiquetée avec le nom d'hôte de votre instance.
+
+
+ Développez la connexion dans le tableau de bord. Mintlify liste chaque groupe auquel votre utilisateur autorisant a un accès Maintainer ou supérieur, ainsi qu'une entrée **Personal projects** pour les projets dans l'espace de noms personnel de l'utilisateur.
+
+ Cochez la case à côté de chaque projet qui doit participer aux automatisations. Mintlify enregistre un webhook sur le projet, génère un jeton secret et le stocke chiffré. À partir de ce moment, Mintlify reçoit les événements push et merge-request de votre instance pour ce projet.
+
+
+ L'utilisateur qui se connecte doit avoir le rôle **Maintainer** sur un projet pour que Mintlify puisse émettre des jetons d'accès de projet à courte durée pendant les exécutions d'automatisation. Sans Maintainer, l'agent peut lire mais ne peut pas pousser de commits ni ouvrir de merge requests.
+
+
+
+
+
+ ## Faire tourner les identifiants
+
+
+Si vous devez modifier le secret client de l'application enregistrée — par exemple après l'avoir renouvelé sur GitLab — supprimez l'instance enregistrée dans Mintlify et ajoutez-la à nouveau avec les nouvelles valeurs. Vous devez d'abord révoquer les connexions OAuth actives ; sinon, Mintlify bloque la suppression.
+
+
+
+ Cliquez sur **Revoke** sur chaque installation listée sous l'instance auto-hébergée. Cela supprime le webhook sur chaque projet connecté et révoque le jeton OAuth sur GitLab.
+
+
+ Dans la carte **Self-hosted GitLab**, cliquez sur **Remove instance**.
+
+
+ Suivez les étapes **Set up the connection** décrites précédemment avec le nouveau secret client.
+
+
+
+
+ ## Dépannage
+
+
+
+ ### `invalid_client` après autorisation
+
+
+GitLab a rejeté l'étape d'échange de jeton car le secret client envoyé par Mintlify ne correspond pas à celui enregistré sur l'application. La cause la plus fréquente est qu'un secret a été modifié sur GitLab — par un **Renew secret** explicite, ou silencieusement lorsque quelqu'un a modifié l'application — et que la valeur dans Mintlify est obsolète.
+
+Solution : faites tourner les identifiants en suivant les étapes [Faire tourner les identifiants](#rotate-credentials) avec le secret actuel.
+
+
+ ### Échec de l'enregistrement du webhook : `Invalid url given`
+
+
+GitLab a refusé d'enregistrer le webhook car l'URL envoyée par Mintlify (`https://app.mintlify.com/gitlab-oauth-webhook`) a été rejetée par la liste d'autorisation des requêtes sortantes de GitLab. Les instances auto-hébergées rejettent les URL « locales » sauf si l'administrateur les autorise explicitement.
+
+Solution : dans la zone d'administration de votre GitLab, accédez à **Settings** \> **Network** \> **Outbound requests** et activez **Allow requests to the local network from webhooks and integrations**. Si votre politique réseau bloque `app.mintlify.com`, contactez votre administrateur réseau pour autoriser le HTTPS sortant vers cet hôte.
+
+
+ ### Aucun écran de consentement lors de l'autorisation
+
+
+Si vous ne voyez pas la boîte de dialogue de consentement de GitLab lors de l'autorisation, soit :
+
+- L'application est marquée **Trusted** sur GitLab. Les applications approuvées sautent le consentement pour tous les utilisateurs. Décochez **Trusted** dans les paramètres de l'application si vous souhaitez que les utilisateurs voient et confirment les portées.
+- Votre utilisateur GitLab a déjà autorisé l'application avec les mêmes portées. GitLab se souvient des autorisations précédentes et saute le consentement lors des autorisations suivantes. Révoquez l'autorisation de l'application dans **User settings** \> **Applications** \> **Authorized applications** pour revoir le consentement.
diff --git a/zh.json b/zh.json
index 3027964e93..3dec3d8db9 100644
--- a/zh.json
+++ b/zh.json
@@ -186,7 +186,8 @@
"zh/deploy/ci",
"zh/deploy/github",
"zh/deploy/ghes",
- "zh/deploy/gitlab"
+ "zh/deploy/gitlab",
+ "zh/deploy/gitlab-self-hosted"
]
},
{
diff --git a/zh/agent/integrations.mdx b/zh/agent/integrations.mdx
new file mode 100644
index 0000000000..474b17fbf8
--- /dev/null
+++ b/zh/agent/integrations.mdx
@@ -0,0 +1,73 @@
+---
+title: "代理集成"
+description: "连接 Slack、Notion、Linear、Jira、Confluence 等应用，以便代理在回答问题和更新内容时拉取实时上下文。"
+keywords: ["集成", "Slack", "Notion", "Linear", "Jira", "Confluence", "Salesforce", "Intercom", "Google Calendar", "Plain", "上下文", "Nango"]
+---
+
+代理集成让代理可以访问团队使用的其他工具中的上下文。连接后，代理可以搜索 Slack 线程、阅读 Notion 页面、查询 Linear 工单，并从其他应用中拉取上下文，以便完善其回复和内容更新。
+
+
+ ## 连接范围
+
+
+集成的连接方式有两种：
+
+- **共享集成**为整个组织一次性连接。团队中的任何人都可以提示代理使用它们。Slack、Notion、Linear、Jira、Confluence、Salesforce、Intercom 和 Plain 都采用这种方式连接。
+- **个人集成**按用户连接。每位团队成员授权自己的账户，代理只能代表连接该集成的用户使用它。Google Calendar 是个人集成。
+
+个人集成将日历事件等用户专属数据限定在连接该集成的用户范围内，而不会在整个组织间共享。
+
+
+ ## 连接集成
+
+
+管理员和编辑者可以代表组织连接共享集成。
+
+1. 前往控制台中的[代理集成](https://app.mintlify.com/settings/organization/integrations)页面。
+2. 找到你想要连接的集成。
+3. 点击 **Connect**。
+4. 按照 OAuth 提示授权 Mintlify 访问你的账户。
+
+某些集成在连接完成之前会打开额外的配置步骤。Jira、Confluence 和 Salesforce 会在 OAuth 流程开始前要求提供你的工作区 URL 或子域名，而 Plain 等基于 API 密钥的提供方会提示你粘贴 API 密钥。
+
+
+ ## 支持的集成
+
+
+| 集成 | 范围 |
+| --- | --- |
+| Confluence | 共享 |
+| Google Calendar | 个人 |
+| Intercom | 共享 |
+| Jira | 共享 |
+| Linear | 共享 |
+| Notion | 共享 |
+| Plain | 共享 |
+| Salesforce | 共享 |
+| Slack | 共享 |
+
+
+ ## 代理如何使用集成
+
+
+代理将已连接的集成作为工具使用。当你向代理提出问题或交付任务时，它可以从已连接的应用中搜索并检索内容，以构建上下文。
+
+例如：
+- “总结关于 v2 API 迁移的 Slack 线程，并整理成知识库文章。”
+- “查看该功能对应的 Linear 工单，并记录其行为。”
+- “团队对限流是怎么决定的？去 Slack 里查一下。”
+
+代理仅在与请求相关时才会访问集成数据。它不会主动从已连接的应用中读取内容。
+
+
+ ## 断开集成
+
+
+1. 前往控制台中的[代理集成](https://app.mintlify.com/settings/organization/integrations)页面。
+2. 找到你想要断开的已连接集成。
+3. 点击 **Configure**。
+4. 点击 **Disconnect**。
+
+断开共享集成会移除组织中所有人的访问权限，代理会立即失去对该工具的访问权。
+
+断开个人集成只会移除你自己的连接。其他连接了相同集成的团队成员仍保留其访问权，代理仍可代表他们使用该集成。
diff --git a/zh/ai/mintlify-mcp.mdx b/zh/ai/mintlify-mcp.mdx
new file mode 100644
index 0000000000..a5d2395f3d
--- /dev/null
+++ b/zh/ai/mintlify-mcp.mdx
@@ -0,0 +1,185 @@
+---
+title: "管理员 Model Context Protocol (MCP) 服务器"
+sidebarTitle: "管理员 MCP"
+description: "让 Claude 和 Cursor 等 AI 工具获得对你的 Mintlify 内容和控制台的写入权限，从而编辑页面、更新设置并提交 PR。"
+keywords: ["MCP", "写入权限", "AI", "编辑", "Claude", "Cursor", "branch", "pull request"]
+---
+
+
+ ## 关于管理员 MCP
+
+
+管理员 MCP 服务器赋予 AI 工具对你的 Mintlify 内容和设置的写入权限。可使用它来更新内容并访问你的控制台。借助管理员 MCP，你可以使用你常用的 AI 工具来编辑页面、调整导航结构、更新 `docs.json`、提交拉取请求、修改设置、创建工作流等等。
+
+将任意 MCP 客户端 (例如 Claude、Claude Code 或 Cursor) 连接到管理员 MCP 服务器，即可使用与编写代码相同的工具协同处理你的 Mintlify 内容和设置。使用管理员 MCP 服务器时，所有更改都会发生在某个 branch 上，并需要通过拉取请求合并。
+
+
+ 管理员 MCP 服务器允许 AI 工具访问你的 Mintlify 控制台。请将其视为拥有写入权限的同事。仅从受信任的 AI 工具连接它，并在合并前审查每一个拉取请求。
+
+
+
+ ### 管理员 MCP 与搜索 MCP 的区别
+
+
+| | 管理员 MCP | 搜索 MCP |
+| :-- | :-- | :-- |
+| **受众** | 你的团队 | 你的终端用户 |
+| **权限** | 读取、编辑、调整结构、保存、创建工作流、管理设置 | 读取并搜索已发布的页面 |
+| **端点** | 由 Mintlify 托管，仅限于你的项目 | 位于你的站点域名上的 `/mcp` |
+| **输出** | 内容编辑、导航更改、拉取请求、工作流运行 | 搜索结果和页面内容 |
+
+
+ ## 连接到管理员 MCP
+
+
+你必须通过 Mintlify 账户完成交互式 OAuth 登录才能连接到管理员 MCP。AI 工具会将该登录会话兑换为限定到单个项目的会话令牌。
+
+
+
+
+
+ 1. 前往 Claude 设置中的 [Connectors](https://claude.ai/settings/connectors) 页面。
+ 2. 点击 **Add custom connector**。
+ 3. 添加连接器
+ - 名称：Admin MCP
+ - URL：`https://mcp.mintlify.com`
+ 4. 点击 **Add** 并完成 OAuth 登录。
+
+
+ 点击附件按钮 (加号图标)，然后选择你的管理员 MCP 服务器。Claude 现在可以在回答你的提示时调用 Mintlify 管理员 MCP 工具。
+
+
+
+
+ 使用 Claude Code CLI 添加管理员 MCP 服务器：
+
+ ```bash
+ claude mcp add --transport http mintlify https://mcp.mintlify.com
+ ```
+
+ 首次使用时，Claude Code 会打开一个浏览器窗口以完成 OAuth 登录。完成认证后，后续调用会复用该会话。
+
+
+ 1. 使用 Command \+ Shift \+ P (Windows 上为 Ctrl \+ Shift \+ P) 打开命令面板。
+ 2. 搜索 **Open MCP settings** 并点击 **Add custom MCP**。
+ 3. 在 `mcp.json` 中添加管理员 MCP：
+
+ ```json
+ {
+ "mcpServers": {
+ "mintlify": {
+ "url": "https://mcp.mintlify.com"
+ }
+ }
+ }
+ ```
+
+ 4. 重新加载 Cursor，并在出现提示时完成 OAuth 登录。
+
+
+
+
+ ## 会话的工作方式
+
+
+每个管理员 MCP 会话都绑定到单个 Git branch。流程如下：
+
+
+
+ 第一次调用必须是 `checkout`。它会从你的部署 branch 基础上创建一个全新的 `mintlify-mcp/-` branch (或附加到你指定的现有 branch)，并返回一个 `editorUrl`，你可以打开它在控制台编辑器中实时跟进。
+
+ 如果你需要发现或筛选仓库中现有的 branch，请在 `checkout` 之前调用 `list_branches`。
+
+
+ AI 使用 `search`、`read`、`list_nodes`、`edit_page`、`write_page`、`create_node` 和 `update_config` 等工具进行更改。所有编辑都会实时缓冲在会话 branch 上——目前还不会影响你的部署 branch。
+
+
+ 随时调用 `diff` 查看与 `main` 相比发生了哪些更改。在控制台中打开 `editorUrl`，可以看到相同更改的渲染效果。
+
+
+ 调用 `save` 将 branch 推送到 Git。使用 `mode: "pr"` (默认值) 创建拉取请求，或使用 `mode: "commit"` 直接推送到现有的 PR branch。
+
+
+ 调用 `discard_session` 丢弃所有会话内更改并释放该 branch。
+
+
+
+
+ 在活动会话期间再次调用 `checkout` 会将会话切换到新的 branch。可借此放弃进行中的草稿，并在不结束对话的情况下重新开始。
+
+
+
+ ## 管理员 MCP 可以做什么
+
+
+
+ ### 内容
+
+
+- **`read`** — 获取会话 branch 上任意页面的完整 MDX。
+- **`search`** — 在所有页面中查找匹配子字符串或正则表达式的行。
+- **`edit_page`** — 对页面进行有针对性的编辑。
+- **`write_page`** — 覆盖页面的完整 MDX 内容。
+
+
+ ### 导航
+
+
+- **`list_nodes`** — 遍历导航树，可使用可选筛选条件。按 `parentId` 筛选 (使用 `recursive: true` 包含所有后代)、按一个或多个节点类型筛选，或按任意分区范围筛选：`language`、`version`、`tab`、`dropdown`、`anchor`、`product` 或 `item`。结果通过不透明的 `cursor` 分页。
+- **`create_node`** — 添加新的页面、组、tab、anchor、版本、语言、产品或 dropdown。
+- **`update_node`** — 就地更新节点属性 (重命名组、更改图标、设置默认版本)。
+- **`move_node`** — 移动节点，包括重命名页面的路径。
+- **`delete_node`** — 从导航中移除节点。
+
+
+ ### 配置
+
+
+- **`update_config`** — 修改 `docs.json` (主题、导航根节点、集成、SEO 设置)。
+
+
+ ### 会话
+
+
+- **`checkout`** — 将会话绑定到某个 branch。
+- **`list_branches`** — 列出项目可用的 Git branch，可选用 `query` 进行筛选。返回 branch 名称、总数以及部署 branch。在 `checkout` 之前调用此项，可按名称附加到现有 branch。
+- **`get_session_state`** — 查看当前 branch、已编辑的文件和待处理的导航差异。
+- **`diff`** — 列出会话与 `main` 之间的所有更改。
+- **`save`** — 打开拉取请求或提交到会话 branch。
+- **`discard_session`** — 丢弃会话及其进行中的更改。
+
+
+ ## 示例提示词
+
+
+连接管理员 MCP 后，你可以使用自然语言提示词来驱动它。例如：
+
+- _“检出一个名为 `add-billing-faq` 的 branch，并在 FAQ 组下创建一个名为 'Billing' 的新页面。为这个 Linear 工单中的五个问题草拟答案。”_
+- _“找出每一个提到已废弃的 `legacy_token` 字段的页面，并将示例更新为使用 `api_key`。保存为一个标题为 'docs: replace legacy\_token references' 的 PR。”_
+- _“重新组织 API 参考：将 webhooks 页面移入名为 'Webhooks' 的新组，并更新图标以与该部分其他内容保持一致。”_
+
+
+ ## 最佳实践
+
+
+
+
+ 每次 `checkout` 都会返回一个 `editorUrl`。在单独的标签页中打开它，这样你就可以在提示时实时观察 AI 的更改在控制台编辑器中渲染。
+
+
+
+ 管理员 MCP 强大到足以在一次会话中重写数百个页面。在合并之前，请阅读 PR 差异并大致浏览渲染预览。不要对大量更改做盲目通过。
+
+
+
+ 向 `checkout` 传入 `slug` (例如 `add-quickstart`)，使自动生成的 branch 易于阅读。如果不传入，branch 名称会基于会话令牌生成，在你的仓库中很难辨识。
+
+
+
+ 让每个会话专注于一项更改。更小的会话能生成更易审查的拉取请求，并能节省代理的上下文窗口。使用 `discard_session` 后再次 `checkout` 以切换到无关的工作。
+
+
+
+
+ 会话在 Mintlify 端会持有一个内存中的 branch。如果你在没有保存或丢弃的情况下放弃会话，该 branch 会一直保留到你下一次 checkout 覆盖它为止。请避免在你的仓库中留下陈旧的 `mintlify-mcp/*` branch，并定期清理它们。
+
diff --git a/zh/credits.mdx b/zh/credits.mdx
new file mode 100644
index 0000000000..633e656c1d
--- /dev/null
+++ b/zh/credits.mdx
@@ -0,0 +1,85 @@
+---
+title: "积分定价"
+description: "了解 Mintlify 积分如何用于助手消息、代理运行和自动化，包括我们如何对积分套餐、超额使用和结转进行计费。"
+keywords: ["积分", "计费", "定价", "AI 聊天", "消息", "套餐", "用量"]
+---
+
+部分 Mintlify 功能会消耗积分。
+
+* 助手回复
+* 编辑器或 Slack 中的代理运行
+* 自动化运行
+
+如需查看最新的定价信息，请参阅 [Pricing 页面](https://mintlify.com/pricing)，或在你的控制台中查看 [Usage](https://app.mintlify.com/settings/organization/usage) 页面。
+
+
+ ## 定价等级
+
+
+| 每月积分 | 每月费用 | 结转上限 |
+|:----------------|:-------------|:-------------|
+| 0 | $0 | 0 |
+| 10,250 | $100 | 15,375 |
+| 26,000 | $250 | 39,000 |
+| 52,500 | $500 | 78,750 |
+| 80,000 | $750 | 120,000 |
+| 108,500 | $1,000 | 162,750 |
+
+如果你每月需要超过 108,500 个积分，请[联系销售](https://www.mintlify.com/contact/sales)以讨论定制方案。
+
+**超额使用**每个积分额外收费 $0.01，而不会自动触发套餐升级。你可以设置用量提醒，在用量达到所在套餐限额的某一百分比时收到邮件通知。根据你的使用模式，允许超额使用可能比升级到更高套餐更划算。
+
+
+ 超额使用默认关闭。你必须在控制台的 [Usage](https://app.mintlify.com/settings/organization/usage) 页面启用。
+
+
+**结转**最多可将未使用积分的 50% 结转到下个月，因此任何月份的最大可用积分为月度限额的 1.5 倍。更改套餐时结转会重置。
+
+更高的套餐每积分的实际成本更低。如果你的用量持续达到当前套餐的上限，升级套餐会比持续支付超额费用更经济。
+
+升级和降级会立即生效，相关费用将按当前计费周期按比例结算。
+
+如需大批量使用或定制积分套餐，请[联系销售](mailto:sales@mintlify.com)。定制积分套餐仅在企业方案下提供。
+
+
+ ## 积分如何使用
+
+
+不同功能在每次交互中消耗的积分数量不同：
+
+| 功能 | 每次交互平均积分 |
+|:--------|:--------------------------------|
+| 助手回复 | 23 |
+| 编辑器代理运行 | 115 |
+| Slack 代理运行 | 110 |
+
+自动化运行时也会消耗积分：
+
+| 自动化 | 每次运行平均积分 |
+|:---------|:------------------------|
+| 根据代码变更更新 | 180 |
+| 根据助手对话更新 | 212 |
+| 失效链接检测 | 285 |
+| Changelog | 223 |
+| SEO 审计 | 422 |
+| 翻译 | 913 |
+| 拼写检查 | 330 |
+| 写作风格 | 235 |
+
+
+ ## 估算你的用量
+
+
+使用[积分如何使用](#how-credits-work)部分中的平均值估算每月所需的积分量。
+
+例如，如果你的文档站点每月处理 500 个助手回复，那大约是 11,500 个积分 (500 × 23)。再添加每周一次的失效链接检测自动化，每月大约会增加 1,140 个积分 (4 × 285)。
+
+在使用积分驱动的功能一个月后，回顾你的使用模式，看看是否需要调整套餐。
+
+
+ ## 成本优化
+
+
+**安排自动化定时运行，而不是在每次推送时触发。** SEO 审计、写作风格检查和失效链接检测等自动化无需在每次代码变更时运行。按每日或每周的 cron 计划运行这些自动化，而不是在每次推送时运行，可以显著减少积分消耗，对内容质量并不会有实质性影响。
+
+**监控你的用量模式。** 控制台中的 [Usage](https://app.mintlify.com/settings/organization/usage) 页面按功能类别展示用量明细。如果某个自动化消耗的积分超出预期，请检查其触发条件或自定义指令。
diff --git a/zh/deploy/gitlab-self-hosted.mdx b/zh/deploy/gitlab-self-hosted.mdx
new file mode 100644
index 0000000000..6551424351
--- /dev/null
+++ b/zh/deploy/gitlab-self-hosted.mdx
@@ -0,0 +1,122 @@
+---
+title: "自托管 GitLab OAuth"
+description: "通过 OAuth 将自托管的 GitLab 实例连接到 Mintlify，让自动化能够代表你克隆存储库、推送提交和发起合并请求。"
+keywords: ["GitLab", "自托管", "OAuth", "自动化", "企业"]
+---
+
+除了 gitlab.com 之外，Mintlify 还支持基于 OAuth 的自托管 GitLab 实例授权。OAuth 允许 Mintlify 代理在自动化运行期间以 GitLab 用户身份进行操作：克隆存储库、推送提交、发起合并请求以及注册项目 webhook。
+
+你必须为自托管的 GitLab 实例配置 OAuth 授权，才能支持[自动化](/zh/automations)。
+
+与 gitlab.com 不同（Mintlify 提供单个 OAuth 应用供每位客户进行授权），每个自托管实例都必须注册自己的 OAuth 应用。请在你的 GitLab 实例上创建应用，将其凭据共享给 Mintlify，然后通过 OAuth 授权来连接用户。
+
+
+ 本指南仅涉及为自动化提供支持的 **OAuth** 集成。你必须使用部署令牌单独配置部署端连接（用于内容同步和预览），请参阅 [GitLab 指南](/zh/deploy/gitlab)。OAuth 集成依赖于部署端连接。
+
+
+
+ ## 前置条件
+
+
+- 拥有自托管 GitLab 实例的管理员权限。
+- 你的 GitLab 实例必须可以从 `https://app.mintlify.com` 访问。位于 VPN 之后或被防火墙阻止公网入站访问的实例无法使用。
+- 你的 Mintlify 组织已启用自托管 GitLab 功能。如果你在 [Git 设置](https://app.mintlify.com/settings/deployment/git-settings)控制台页面中未看到 **Self-hosted GitLab** 部分，请联系支持团队。
+
+
+ ## 设置连接
+
+
+
+
+ 在自托管 GitLab 中，以管理员身份登录并依次前往 **Admin Area** \> **Applications** \> **Add new application**。
+
+ 使用以下值配置应用：
+
+ - **Name**：`Mintlify`
+ - **Redirect URI**：`https://app.mintlify.com/api/gitlab-oauth/callback`
+ - **Trusted**：保持**未勾选**。将应用标记为 Trusted 会跳过每位用户的同意界面；保持未勾选状态可在每位用户首次连接时显示正常的授权提示。
+ - **Confidential**：**勾选**。Mintlify 是服务端客户端，会对密钥保密。
+ - **Scopes**：选择 `api`、`read_repository` 和 `write_repository`。代理会使用这些权限读取项目元数据、克隆存储库以及推送提交。
+
+ 点击 **Save application**。
+
+
+ 在 GitLab 上编辑 OAuth 应用可能会静默地轮换客户端密钥。如果你稍后做出更改，请点击 **Renew secret** 并在 Mintlify 中更新新的值。
+
+
+
+ 保存后，GitLab 会显示应用的 **Application ID** 和 **Secret**。请保持此页面打开——密钥只会显示一次。
+
+
+ 在 Mintlify 控制台中，打开 **Settings** \> **Git settings**，找到 **GitLab OAuth** 下的 **Self-hosted GitLab** 部分。
+
+ 点击 **Connect Self-Hosted GitLab** 并输入：
+
+ - **GitLab instance URL**：你的 GitLab 实例的公网 URL，例如 `https://gitlab.your-company.com`。Mintlify 在交换令牌和调用 GitLab API 时会通过此 URL 访问你的实例。
+ - **OAuth application client ID**：上一步中的 **Application ID**。
+ - **OAuth application client secret**：上一步中的 **Secret**。
+
+ 点击 **Save instance**。Mintlify 会对密钥进行静态加密，保存后绝不会再将其返回到浏览器。
+
+
+ 点击 **Authorize self-hosted GitLab**。系统会将你重定向至你的 GitLab 实例，必要时提示登录，并显示列出所请求权限范围的同意界面。
+
+ 在 GitLab 上点击 **Authorize** 之后，你会被重定向回 Mintlify，新建的连接将显示在已安装列表中，并以你的实例主机名作为标识。
+
+
+ 在控制台中展开该连接。Mintlify 会列出授权用户拥有 Maintainer 或更高访问权限的每个群组，以及一个 **Personal projects** 条目（用于用户个人命名空间下的项目）。
+
+ 勾选每个应参与自动化的项目旁的复选框。Mintlify 会在项目上注册 webhook，生成一个密钥令牌，并将其加密存储。从那时起，Mintlify 会接收你的实例针对该项目发送的推送和合并请求事件。
+
+
+ 连接的用户必须在项目上具有 **Maintainer** 角色，Mintlify 才能在自动化运行期间生成短期项目访问令牌。没有 Maintainer 权限时，代理可以读取但无法推送提交或发起合并请求。
+
+
+
+
+
+ ## 轮换凭据
+
+
+如果你需要更改已注册应用的客户端密钥——例如在 GitLab 上更新密钥后——请在 Mintlify 中删除已保存的实例，并使用新值重新添加。你必须先撤销活动的 OAuth 连接，否则 Mintlify 会阻止删除。
+
+
+
+ 点击自托管实例下列出的每个安装上的 **Revoke**。这将移除每个已连接项目上的 webhook，并撤销 GitLab 上的 OAuth 令牌。
+
+
+ 在 **Self-hosted GitLab** 卡片中，点击 **Remove instance**。
+
+
+ 使用新的客户端密钥按照前述的 **Set up the connection** 步骤进行操作。
+
+
+
+
+ ## 故障排查
+
+
+
+ ### 授权后出现 `invalid_client`
+
+
+GitLab 拒绝了令牌交换步骤，因为 Mintlify 发送的客户端密钥与应用上注册的不匹配。最常见的原因是 GitLab 上的密钥被轮换了——由显式的 **Renew secret** 操作触发，或在有人编辑应用时静默轮换——而 Mintlify 中的值已过时。
+
+修复方法：使用当前密钥按照[轮换凭据](#rotate-credentials)的步骤轮换凭据。
+
+
+ ### Webhook 注册失败：`Invalid url given`
+
+
+GitLab 拒绝注册 webhook，因为 Mintlify 发送的 URL（`https://app.mintlify.com/gitlab-oauth-webhook`）被 GitLab 的出站请求白名单拒绝。自托管实例会拒绝"本地"URL，除非管理员明确允许。
+
+修复方法：在 GitLab 管理区域中，依次前往 **Settings** \> **Network** \> **Outbound requests**，启用 **Allow requests to the local network from webhooks and integrations**。如果你的网络策略阻止 `app.mintlify.com`，请联系网络管理员，允许出站 HTTPS 流量到达该主机。
+
+
+ ### 授权时没有同意界面
+
+
+如果你在授权时没有看到 GitLab 的同意对话框，可能是以下原因之一：
+
+- 该应用在 GitLab 上被标记为 **Trusted**。Trusted 应用会跳过所有用户的同意环节。如果你希望用户看到并确认权限范围，请在应用设置中取消勾选 **Trusted**。
+- 你的 GitLab 用户之前已使用相同的权限范围授权了该应用。GitLab 会记住先前的授权，并在后续授权时跳过同意环节。请在 **User settings** \> **Applications** \> **Authorized applications** 中撤销该应用的授权，以再次查看同意界面。
diff --git a/zh/editor/agent.mdx b/zh/editor/agent.mdx
new file mode 100644
index 0000000000..a154eaf143
--- /dev/null
+++ b/zh/editor/agent.mdx
@@ -0,0 +1,126 @@
+---
+title: "向代理提问"
+description: "使用编辑器内置的 AI 代理，通过聊天界面撰写内容、编辑页面、跨站点搜索、上传文件并配置设置。"
+keywords: ["编辑器", "AI", "助手", "代理", "聊天", "code mode", "文件上传"]
+---
+
+编辑器内置了一个代理，可以编辑页面、重新组织导航、更新 `docs.json`、在整个仓库中搜索以及管理控制台设置。
+
+编辑器代理会直接在你的当前 branch 中进行更改。
+
+
+ ## 打开代理
+
+
+点击编辑器工具栏中的 **Ask agent**，或按 Cmd + I (macOS) 或 Ctrl + I (Windows)。
+
+要关闭面板，请点击面板标题栏中的 **X** 按钮，或再次按 Cmd + I。
+
+
+ ## 发送消息
+
+
+在面板底部的聊天框中输入你的请求，按 Enter 或点击 发送按钮。
+
+输入 @ 可以提及特定页面。代理在处理你的请求时会聚焦于该页面。如果你不提及任何页面，代理会使用你当前打开的页面。
+
+示例提示词：
+
+- `simplify the introduction page`
+- `fix all grammar errors across my content`
+- `add a new page that explains authentication`
+- `rename every mention of "Acme Pro" to "Acme Team" across all pages`
+- `update docs.json to add a new group called "Guides"`
+
+
+ ## 附加文件
+
+
+点击聊天框中的回形针图标，或将文件拖放到面板上。代理会读取附加的文件作为请求的上下文。
+
+支持的文件类型：
+- **图像**：JPG、PNG、GIF、WebP、SVG
+- **文档**：PDF
+- **代码和文本**：`.js`、`.ts`、`.jsx`、`.tsx`、`.mdx`、`.md`、`.json`、`.yaml`、`.html`、`.css`、Python、Go、Rust、Ruby、Java、Swift、C、C++、SQL、shell 脚本等
+
+最大大小：每个文件 5 MB。最多：每条消息 10 个文件。
+
+
+ ## 将选中内容添加到代理
+
+
+在可视化模式下，在页面上选中文本。选区上方会出现一个浮动工具栏。点击 **Add to agent**，将所选文本作为上下文发送给代理。
+
+
+ ## 查看代理的更改
+
+
+代理在编辑页面时，聊天中会出现 **Changed files** 面板。展开后可看到本次会话中修改的每个文件的列表。点击任意文件可在差异视图中打开它，将代理的更改与原文对比。
+
+
+ ## 代理可以做什么
+
+
+
+ ### 编辑页面
+
+
+代理可以在任意页面上撰写、改写、扩展和重新组织内容。它会阅读你现有的内容，以匹配你的风格和结构。
+
+
+ ### 搜索并浏览你的内容
+
+
+代理可以在整个仓库中搜索，而不仅限于你当前打开的页面。可借助它查找信息、检查不一致之处，或在添加内容前确认内容是否已经存在。
+
+
+ ### 更新导航和 docs.json
+
+
+代理可以添加、重命名、重新排序和删除导航元素，这与你在导航面板中手动进行的更改相同。它还可以直接更新 `docs.json` 配置，包括添加新组、调整设置和配置重定向。
+
+示例：`add a "Quickstart" group under the Getting Started tab and move the quickstart page into it`
+
+
+ ### 运行 bash 命令
+
+
+代理可以对你的仓库运行 `grep`、`rg` 和其他 bash 命令。可用于跨多个文件的批量操作。
+
+示例：`find every page that mentions the deprecated /v1/auth endpoint`
+
+
+ ### 配置你的站点 (code mode)
+
+
+对于超出页面编辑范围的请求 (例如设置身份验证、管理工作流或更改部署设置)，代理会切换到 code mode。它会代你编写并对 Mintlify 控制台运行脚本。
+
+Code mode 会遵循你在控制台中的权限。如果你在控制台中无权访问某项设置，代理也无法更改它。
+
+会使用 code mode 的示例提示词：
+
+- `enable JWT authentication for my site`
+- `create a workflow that updates my site when I merge a PR`
+- `add a custom domain`
+
+
+ ### 继续自动化运行
+
+
+当你通过点击 **View changes** 从已完成的自动化运行中打开编辑器时，代理面板会自动打开，并带有关于该自动化所执行操作的上下文。聊天顶部会显示一张 **Changed pages** 卡片，列出该自动化修改的每个页面——点击任意页面可打开差异视图。
+
+代理拥有该自动化提示词、所做更改的摘要以及它修改的页面的上下文。你可以让它细化或扩展该自动化的工作，无需再次说明背景。
+
+例如：`The new section on rate limits is too long. Trim it to three sentences.`
+
+
+ ## 会话历史
+
+
+点击面板标题栏中的时钟图标，可查看你之前的聊天会话。点击任意会话可重新打开它，并查看代理的更改。
+
+
+ ## AI 指令
+
+
+要为代理提供持久性指引 (例如语气规则、术语或格式约定)，请在[编辑器设置](/zh/editor/settings#ai-instructions)中配置 AI 指令。代理会在每次请求时遵循这些指令，无需你重复说明。
diff --git a/zh/editor/branching-and-publishing.mdx b/zh/editor/branching-and-publishing.mdx
new file mode 100644
index 0000000000..ef9db1fdf0
--- /dev/null
+++ b/zh/editor/branching-and-publishing.mdx
@@ -0,0 +1,224 @@
+---
+title: "分支与发布"
+description: "了解分支及保护规则如何决定发布时所发生的操作，以及如何管理完整的审查与部署工作流。"
+keywords: ["编辑器", "分支", "发布", "拉取请求", "预览", "git", "合并", "部署"]
+---
+
+Web 编辑器会在你输入时自动保存所有内容，但你的更改只有在你选择发布后才会上线。
+
+发布时所发生的具体操作取决于两件事：**你当前所在的分支**，以及**该分支是否要求拉取请求**。
+
+
+ ## 保存与发布
+
+
+**保存**会自动进行。Mintlify 会将你的编辑存储在其服务器上，并在浏览器标签页、设备以及网络中断之间保留这些内容。
+
+**发布**会将你的更改提交到你的 Git 存储库。点击工具栏中的 **Publish** 以打开发布菜单，将你的更改保存为一次 Git 提交，并创建一个拉取请求。
+
+编辑器会将以下内容作为待处理的更改进行跟踪：
+
+- 页面中的内容编辑
+- 新建或删除的页面
+- 导航结构的更改
+- 媒体上传
+- 配置更新
+
+
+ ## 发布时会发生什么
+
+
+点击发布按钮后可用的操作取决于你当前所在的分支，以及该分支是否设置了要求拉取请求的分支保护规则。
+
+| 分支类型 | 分支保护 | 可用操作 |
+|-------------|-------------------|-------------------|
+| 部署用分支 | 无 | **Publish** 直接发布到你的线上站点 |
+| 部署用分支 | 需要拉取请求 | **Create branch** 将更改转移到新分支 |
+| 功能分支 | 无 | **Save in branch**、**Create pull request** |
+| 功能分支 | 需要拉取请求 | **Save in branch**、**Create pull request** |
+
+- **Publish**：立即将你的更改提交并部署到线上站点。
+- **Save in branch**：将更改提交到功能分支，但不合并到部署用分支。
+- **Create branch**：当你在受保护的部署用分支上时，将待处理的更改转移到一个新的功能分支。
+- **Create pull request**：打开一个以你的部署用分支为目标的拉取请求。
+
+如果没有待处理的更改，编辑器会禁用发布和保存操作。
+
+
+ 在 Mintlify 构建并部署你的更改后，你的线上站点会更新。这通常需要 30 秒到几分钟。请在你的 [dashboard](https://app.mintlify.com) 上查看部署状态。
+
+
+
+ ## 何时使用分支
+
+
+如果你不使用基于 Git 的工作流，请**直接在部署用分支上编辑**。
+
+当你使用基于分支的工作流，且每次更改都在单独的分支上进行时，请**创建一个分支**。
+
+
+ ## 创建和切换分支
+
+
+
+ ### 创建分支
+
+
+1. 点击编辑器工具栏中的分支名称。
+1. 点击 **Create new branch**。
+1. 如果你有待处理的更改，选择是将它们带到新分支，还是留在当前分支上。
+1. 输入名称并点击 **Create branch**。
+
+
+ 使用具有描述性的分支名称，这样你能轻松识别它们，其他人也能理解每个分支的用途。
+
+
+
+ ### 切换分支
+
+
+1. 点击工具栏中的分支名称。
+1. 搜索或滚动到你想要的分支。
+1. 点击分支以切换到该分支。
+
+
+ 在你有未发布更改时切换分支，编辑器会提示你将这些更改带到新分支，或者将它们留下。留下的更改会保留在原始分支上。
+
+
+
+ 要复制分支名称，将鼠标悬停在下拉菜单中的分支上并点击复制图标。在与团队成员共享分支或在拉取请求中引用它时，这会很有用。
+
+
+
+ ## 预览你的更改
+
+
+每次你将更改保存到功能分支时，Mintlify 会构建一个预览部署——一个临时 URL，你的更改会在那里以发布后完全相同的样子呈现。
+
+
+ ### 访问并分享预览
+
+
+1. 点击编辑器工具栏中的 **Publish**。
+1. 在发布菜单中，点击预览 URL。URL 格式为 `organization-branch-name.mintlify.app`。
+
+ 
+ 
+
+
+复制该 URL 并发送给审查者。每次保存到该分支时，预览都会自动更新。
+
+
+ ### 限制对预览的访问
+
+
+预览 URL 默认是公开可访问的。要将访问限制为你的 Mintlify 组织成员，请在控制台的 [Add-ons](https://app.mintlify.com/products/addons) 页面中启用预览身份验证。
+
+
+ ### 分享编辑器链接
+
+
+要邀请团队成员到某个分支上的特定页面，请从你的浏览器地址栏复制 URL 并分享出去。任何有权限访问你的 Mintlify 组织的人都可以直接在他们的编辑器会话中打开该链接。
+
+URL 格式为：
+
+```text
+https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}
+```
+
+例如：`https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx`
+
+
+ ## 审查并合并拉取请求
+
+
+当当前分支有打开的拉取请求时，发布菜单会显示一个审查面板，其中包含：
+
+- 拉取请求的标题、描述以及是否为草稿。
+- 源分支和目标分支。
+- 更改的文件数量。
+- 部署用分支上的审批要求：**Approval required**、**Code owner required** 或无要求。
+- 当前的审查状态：**Approved**、**Changes requested** 或 **Awaiting review**。
+
+点击 **Open in GitHub** 或 **Open in GitLab** 可在你的 Git 服务提供商中查看拉取请求。
+
+在审查者批准拉取请求后，点击 **Merge and publish** 可直接从编辑器中合并并部署。编辑器会在合并后切换到你的部署用分支。
+
+
+ ### 在编辑器中批准拉取请求
+
+
+对于 GitHub 存储库，审查者可以在编辑器中批准打开的拉取请求。当有打开的拉取请求时，如果你的账户具有审查权限，审查面板中会出现 **Approve pull request** 按钮。当更改可以合并时，点击 **Approve pull request**。审查状态会更新为 **Approved**，并且 **Merge and publish** 操作将变为可用。
+
+对于草稿拉取请求、你已批准的拉取请求或 GitLab 合并请求，批准操作不可用。点击 **Open in GitLab** 可在 GitLab 中批准合并请求。
+
+
+ 在你的 Git 服务提供商中配置分支保护规则以要求拉取请求。请参阅 GitHub 文档中的 [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) 或 GitLab 文档中的 [Protected branches](https://docs.gitlab.com/user/project/repository/branches/protected/)。
+
+
+
+ ### 在合并前审查更改
+
+
+点击发布菜单中任何已更改的文件，即可在差异视图中打开它，并将你的分支与已发布版本进行比较。在可视化模式下，你会看到可视化差异；在源代码模式下，你会看到文本差异。无法显示差异的文件（如图片或已删除的文件）会出现在列表中，但不可点击。
+
+已变更的页面会在文件树中高亮显示，让你一眼就能看出 [automation](/zh/automations) 或团队成员改动了哪些文件。出现在分支差异中的未列出页面，即使它们不在站点导航中，也可以从发布菜单中打开。
+
+
+ ### 在编辑器中打开自动化运行
+
+
+当 [automation](/zh/automations) 打开一个拉取请求时，你可以直接从运行审查 UI 或其 Slack 通知跳转到编辑器，并切换到该自动化的分支：
+
+- 在控制台的 **Automation Runs** 页面中，点击已完成运行上的 **Open in editor**。
+- 在 Slack 通知中，点击 **View changes** 链接。
+
+任一入口都会打开编辑器并切换到该自动化的分支，发布菜单中会预选已变更的页面，让你无需离开编辑器即可审查差异并合并或请求更改。
+
+
+ ### 同时发布
+
+
+每个分支同一时刻只能有一次发布。如果另一位团队成员正在向同一分支发布，请等待当前发布完成后再重试。
+
+
+ ### 提交信息
+
+
+发布时，你可以在确认前输入提交信息。如果留空，编辑器会使用默认信息，其中列出你创建、更新、移动或删除的文件。
+
+
+ ## 解决冲突
+
+
+当你的分支和部署用分支对同一文件有不兼容的更改时，就会发生冲突。例如，你和团队成员编辑了同一文件中的同一行，或将文件移动到了不同位置。
+
+当冲突阻止发布时，编辑器会显示警告。按照提示选择保留每个冲突部分中的哪个版本。
+
+
+ ## 实时协作
+
+
+当多人在同一分支上打开同一页面时，他们会实时一起编辑。每个人的光标和编辑对所有人都可见，并在工具栏中显示头像。
+
+- 来自所有协作者的更改会自动合并。两个人编辑同一部分不会产生冲突。
+- 撤销只会影响你自己的编辑。
+- 如果你的连接断开，编辑会在本地保存，并在重新连接时同步。
+
+当 [Mintlify agent](/zh/agent) 通过 API 或 MCP 编辑页面时，它会像任何其他协作者一样出现在编辑器中。你会在工具栏中看到该代理的头像，并在其最近编辑位置看到一个实时光标。代理完成后，光标会自动消失。
+
+
+ ## Git 同步
+
+
+当有人从编辑器之外向你的存储库推送更改时，编辑器会自动合并这些更改。
+
+不重叠的更改会自动应用。如果远程更改和你的本地编辑影响了页面的同一部分，编辑器会高亮该冲突，以便你解决它。
+
+
+ ## 提交签名
+
+
+在你的[账户设置](https://app.mintlify.com/settings/account)中授权你的 GitHub 账号，即可用该账号对提交进行签名。若未完成授权，则由 Mintlify GitHub 应用对在 Web 编辑器中完成的提交进行签名。
+
+有关编辑器操作如何映射到 Git 操作的参考，请参阅 [Git 基础](/zh/editor/git-essentials#how-the-editor-maps-to-git)。
diff --git a/zh/editor/tutorial.mdx b/zh/editor/tutorial.mdx
new file mode 100644
index 0000000000..b86dfd3f94
--- /dev/null
+++ b/zh/editor/tutorial.mdx
@@ -0,0 +1,70 @@
+---
+title: "如何使用编辑器"
+description: "Mintlify 编辑器的分步演练：创建分支、编辑页面、分享预览部署以供审查，然后发布你的更改。"
+keywords: ["编辑器", "教程", "分支", "发布"]
+---
+
+本教程将引导你使用编辑器完成一次完整的内容更新。你将创建一个分支、进行更改、分享预览以供审查，然后发布你的更改。
+
+
+
+ 分支是你内容的临时副本。这是你在不影响线上站点的情况下进行更改的地方。
+
+ 可以把分支想象成草稿。你可以将它们合并到线上站点，或在选择不进行更改时安全地丢弃它们。
+
+ 在分支上工作可以让你的编辑与线上站点保持隔离，直到你准备好与用户分享内容为止。
+
+ 1. 在编辑器工具栏中，点击分支名称（通常为 `main`）。
+
+ 
+ 
+
+ 1. 点击 **Create new branch**。
+ 1. 输入一个描述你的更改的名称，例如 `update-quickstart`。
+ 1. 点击 **Create branch**。
+
+ 编辑器会切换到你的新分支。你所做的任何更改都只在该分支上。只有在你完成发布流程后，它们才会出现在你的线上站点上。
+
+
+ 编辑现有页面或创建新页面。
+
+ **编辑页面**：点击导航侧边栏中的页面名称将其打开。直接在编辑器中输入以添加内容。按下 / 可插入组件、图片或其他内容。
+
+ **创建页面**：点击你想要添加页面的导航分组旁边的 加号按钮，然后点击 **Add a page** 并输入文件名。
+
+
+ 
+ 
+
+
+
+
+ 当你准备好接受审查时，从你的分支创建一个拉取请求。拉取请求是一个将你的更改合并到构建线上站点的分支的提议。只有在有人批准并合并拉取请求后，你的更改才会上线。
+
+ 1. 点击工具栏中的 **Publish** 以打开发布菜单。
+
+ 
+ 
+
+ 1. 可选：点击列表中任意已更改的文件，查看并将你的编辑与已发布版本进行对比。
+ 1. 点击 **Create pull request**。添加标题和描述，然后点击 **Publish pull request**。
+
+
+ 你也可以点击 **Save in branch**，先提交你的更改而不立即打开拉取请求。如果你想在请求审查之前继续编辑，这会很有用。
+
+
+ 创建拉取请求后，预览部署会自动构建。发布菜单会显示预览 URL——一个临时链接，你的更改会在那里以线上站点上的样子完全呈现。将此 URL 分享给你的审查者。
+
+
+ 将拉取请求分享给你的团队。审查者可以在 GitHub 或 GitLab 中打开拉取请求，留下评论、请求更改或批准它。
+
+ 如果审查者请求更改，请在同一分支上的编辑器中进行编辑。你的更新会自动推送到现有的拉取请求。你不需要创建新的。
+
+ 当所有必需的审查者都批准后，拉取请求即可合并。
+
+
+ 在拉取请求获得批准后，点击工具栏中的 **Publish** 以重新打开发布菜单。该菜单现在会显示拉取请求的状态以及合并选项。
+
+ 点击 **Merge and publish**。编辑器会合并拉取请求，并将你切换回部署用分支。Mintlify 会构建并部署你的更改。你的线上站点会在大约 30 秒到几分钟内更新。
+
+
diff --git a/zh/optimize/search.mdx b/zh/optimize/search.mdx
new file mode 100644
index 0000000000..7fe9392647
--- /dev/null
+++ b/zh/optimize/search.mdx
@@ -0,0 +1,93 @@
+---
+title: "搜索"
+description: "配置你的 Mintlify 文档站点上的站内搜索栏，包括排名加权和每次查询返回的结果数量。"
+keywords: ["搜索", "搜索排名", "搜索加权", "加权", "搜索优先级", "最大搜索结果数", "最大结果数"]
+---
+
+配置你 Mintlify 托管的文档站点上的搜索栏的行为。这些设置仅影响站内搜索。它们不会改变外部搜索引擎对你页面的索引方式。
+
+
+ ## 提升搜索排名
+
+
+使用 `boost` 让特定页面或章节在站内搜索中获得更高的排名权重。该值是一个应用于每个内容片段相关性得分的数值乘数：`boost: 3` 会使某个片段的相关性提升为没有加权时的三倍。
+
+
+ ### 为单个页面加权
+
+
+在页面的 [frontmatter](/zh/organize/pages) 中设置 `boost`，可放大其搜索排名。
+
+```mdx
+---
+title: "Custom domain"
+description: "Connect your custom domain to your Mintlify documentation."
+boost: 3
+---
+```
+
+
+ ### 为导航分组加权
+
+
+在 `docs.json` 导航中的某个分组上设置 `boost`，可将该乘数应用于其下的每个页面。
+
+```json
+{
+ "navigation": {
+ "groups": [
+ {
+ "group": "Get started",
+ "boost": 5,
+ "pages": [
+ "quickstart",
+ "concepts"
+ ]
+ }
+ ]
+ }
+}
+```
+
+页面会从最近一个设置了加权值的祖先那里继承加权因子。子页面或嵌套分组可以通过设置自己的 `boost` 值来覆盖继承的加权。页面 frontmatter 中的 `boost` 始终优先于从导航继承的值。
+
+
+ ### 降低内容优先级
+
+
+使用小于 `1` 的值可将页面在搜索结果中下推。例如，`boost: 0.5` 会将页面的相关性得分相对于其他页面减半。`boost` 为 `1` 时等同于不加权。
+
+```mdx
+---
+title: "Deprecated API"
+description: "Documentation for the deprecated v1 API."
+boost: 0.25
+---
+```
+
+
+ 加权因子会与已有的相关性得分相乘。请谨慎使用。过大的乘数会导致相关性较低的页面在搜索结果中占据主导地位，从而降低整体搜索质量。
+
+
+
+ ## 最大搜索结果数
+
+
+通过控制台控制搜索栏每次查询返回的结果数量。默认值为 `6` 个结果。你可以设置 `1` 到 `100` 之间的任意值。
+
+在控制台中，依次进入 **Settings** > **Deployment** > **Search**，将 **Maximum search results** 设置为你想要的值，然后选择 **Save changes**。
+
+
+ 
+ 
+
+
+较高的值会在每次查询中呈现更多匹配，这对覆盖主题广泛、用户期望浏览许多候选项的站点很有用。较低的值会让结果面板保持紧凑，并促使用户关注排名最高的匹配项。