From c647247d89af575cfce03f72a7788e700993044b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 23 Sep 2026 10:11:01 +0000 Subject: [PATCH 1/4] docs: fix prerequisites and invalid MDX troubleshooting gaps --- editor/tutorial.mdx | 9 +++++++++ help-center/publish-button-disabled-invalid-mdx.mdx | 11 ++++++++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/editor/tutorial.mdx b/editor/tutorial.mdx index 16726d9f0..0d57247c1 100644 --- a/editor/tutorial.mdx +++ b/editor/tutorial.mdx @@ -6,6 +6,13 @@ keywords: ["editor", "tutorial", "branch", "publish"] This tutorial walks you through a complete content update using the editor. You'll create a branch, make a change, share a preview for review, and publish your changes. + + **Prerequisites** + + - Access to the editor at [app.mintlify.com](https://app.mintlify.com). See [Web editor](/editor) for a tour of the interface. + - The **admin** or **editor** role. Viewers can edit on a branch and leave [comments and suggestions](/editor/collaborate), but they can't publish or request review. See [Roles](/dashboard/roles). + + A branch is a temporary copy of your content. It's where you make your changes without affecting your live site. You can merge a branch into your live site or safely discard it if you choose not to make the changes. @@ -21,6 +28,8 @@ This tutorial walks you through a complete content update using the editor. You' 1. Click **New branch**. The editor switches to your new branch. Any changes you make are only on the branch, and they commit to the branch automatically as you work. They only appear on your live site if you complete the publishing process. + + To discard a branch instead of publishing, hover over it in the branch menu and click **Delete branch**. See [Delete a branch](/guides/branches#delete-a-branch). Edit an existing page or create a new one. diff --git a/help-center/publish-button-disabled-invalid-mdx.mdx b/help-center/publish-button-disabled-invalid-mdx.mdx index c55310cbf..10bc2913f 100644 --- a/help-center/publish-button-disabled-invalid-mdx.mdx +++ b/help-center/publish-button-disabled-invalid-mdx.mdx @@ -14,13 +14,22 @@ The tooltip tells you how many pages have errors. The same error blocks **Reques While a page has invalid MDX or invalid frontmatter YAML, those edits stay local to you. Teammates editing the same page only receive valid content, so a syntax error you introduce doesn't overwrite their work. See [Collaborate in the editor](/editor/collaborate) for how real-time editing handles invalid content. +## Find the affected page + +If the tooltip reports one broken page, it's usually the page you're editing. If it reports more than one, or you don't know which page has the error, check each page you've changed on the branch: + +1. Click **Publish** in the toolbar to open the publish menu. The menu lists every changed file on your branch. +2. Open each changed file in turn and look for parsing errors in source mode (see below). Pages that parse successfully render normally; the broken page shows the error. + ## Fix the error manually 1. Open the affected page in the editor. 2. Switch to source mode with Cmd + Shift + S (macOS) or Ctrl + Shift + S (Windows). Source mode highlights the invalid MDX and shows the parsing error. 3. Fix the syntax. Once the page parses, the error clears and the **Publish** button becomes available again. +For frontmatter errors, check that every value is valid YAML: quote strings that contain colons or special characters, keep indentation consistent, and close every quote. See [Page metadata](/organize/pages#page-metadata) for the supported frontmatter fields. + ## Fix the error with the agent 1. Open the editor panel. -2. Prompt the agent to fix any invalid MDX or frontmatter YAML. +2. Prompt the agent to fix any invalid MDX or frontmatter YAML. Without a mention, the agent uses the page you have open as its initial context. To fix errors across the branch in one prompt, ask the agent to find and repair every page with invalid MDX. See [Agent](/editor/agent). From 8c04cce42715ce49d9f0ffbd85897b8336b3bc7c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 23 Sep 2026 10:14:45 +0000 Subject: [PATCH 2/4] docs: mirror English changes into es, fr, zh --- es/editor/tutorial.mdx | 9 +++++++++ .../publish-button-disabled-invalid-mdx.mdx | 15 +++++++++++++-- fr/editor/tutorial.mdx | 9 +++++++++ .../publish-button-disabled-invalid-mdx.mdx | 17 +++++++++++++++-- zh/editor/tutorial.mdx | 9 +++++++++ .../publish-button-disabled-invalid-mdx.mdx | 17 +++++++++++++++-- 6 files changed, 70 insertions(+), 6 deletions(-) diff --git a/es/editor/tutorial.mdx b/es/editor/tutorial.mdx index e807583b5..9170397c5 100644 --- a/es/editor/tutorial.mdx +++ b/es/editor/tutorial.mdx @@ -6,6 +6,13 @@ keywords: ["editor", "tutorial", "branch", "publish"] Este tutorial le guía a través de una actualización completa de contenido usando el editor. Creará una branch, hará un cambio, compartirá una vista previa para su revisión y publicará sus cambios. + + **Requisitos previos** + + - Acceso al editor en [app.mintlify.com](https://app.mintlify.com). Consulte [Editor web](/es/editor) para un recorrido por la interfaz. + - El rol de **administrador** o **editor**. Los espectadores pueden editar en una branch y dejar [comentarios y sugerencias](/es/editor/collaborate), pero no pueden publicar ni solicitar revisión. Consulte [Roles](/es/dashboard/roles). + + Una branch es una copia temporal de su contenido. Es donde realiza sus cambios sin afectar a su sitio publicado. Puede hacer merge de una branch en su sitio publicado o descartarla de forma segura si decide no aplicar los cambios. @@ -21,6 +28,8 @@ Este tutorial le guía a través de una actualización completa de contenido usa 1. Haga clic en **New branch**. El editor cambia a su nueva branch. Cualquier cambio que realice está solo en la branch, y se hace commit en la branch automáticamente mientras trabaja. Solo aparecerán en su sitio publicado si completa el proceso de publicación. + + Para descartar una branch en lugar de publicarla, pase el cursor sobre ella en el menú de branches y haga clic en **Delete branch**. Consulte [Eliminar una branch](/es/guides/branches#delete-a-branch). Edite una página existente o cree una nueva. diff --git a/es/help-center/publish-button-disabled-invalid-mdx.mdx b/es/help-center/publish-button-disabled-invalid-mdx.mdx index c147e9f96..ed8b1b0d9 100644 --- a/es/help-center/publish-button-disabled-invalid-mdx.mdx +++ b/es/help-center/publish-button-disabled-invalid-mdx.mdx @@ -14,6 +14,15 @@ El tooltip te indica cuántas páginas tienen errores. El mismo error bloquea ** Mientras una página tiene MDX no válido o YAML de frontmatter no válido, esas ediciones permanecen locales para ti. Los compañeros que editen la misma página solo reciben contenido válido, así que un error de sintaxis que introduzcas no sobrescribe su trabajo. Consulta [Colaborar en el editor](/es/editor/collaborate) para ver cómo gestiona la edición en tiempo real el contenido no válido. +
+ ## Localizar la página afectada +
+ +Si el tooltip indica una sola página con errores, normalmente es la que estás editando. Si indica más de una, o no sabes qué página tiene el error, revisa cada página que hayas modificado en la branch: + +1. Haz clic en **Publish** en la barra de herramientas para abrir el menú de publicación. El menú lista todos los archivos modificados en tu branch. +2. Abre cada archivo modificado por turno y busca errores de parseo en el modo source (ver más abajo). Las páginas que se parsean correctamente se muestran con normalidad; la página rota muestra el error. +
## Corregir el error manualmente
@@ -22,9 +31,11 @@ Mientras una página tiene MDX no válido o YAML de frontmatter no válido, esas 2. Cambia al modo source con Cmd + Shift + S (macOS) o Ctrl + Shift + S (Windows). El modo source resalta el MDX no válido y muestra el error de parseo. 3. Corrige la sintaxis. Una vez que la página se parsea, el error desaparece y el botón **Publish** vuelve a estar disponible. +Para errores de frontmatter, comprueba que cada valor sea YAML válido: entrecomilla las cadenas que contengan dos puntos o caracteres especiales, mantén una sangría coherente y cierra todas las comillas. Consulta [Metadatos de la página](/es/organize/pages#page-metadata) para ver los campos de frontmatter admitidos. +
- ### Corregir el error con el agente + ## Corregir el error con el agente
1. Abre el panel del editor. -2. Pide al agente que corrija cualquier MDX o YAML de frontmatter no válido. +2. Pide al agente que corrija cualquier MDX o YAML de frontmatter no válido. Sin una mención, el agente usa la página que tienes abierta como contexto inicial. Para corregir errores en toda la branch con una sola petición, pide al agente que encuentre y repare todas las páginas con MDX no válido. Consulta [Agente](/es/editor/agent). diff --git a/fr/editor/tutorial.mdx b/fr/editor/tutorial.mdx index fefb18ecf..f5360aac2 100644 --- a/fr/editor/tutorial.mdx +++ b/fr/editor/tutorial.mdx @@ -6,6 +6,13 @@ keywords: ["editor", "tutorial", "branch", "publish"] Ce tutoriel vous guide à travers une mise à jour de contenu complète avec l'éditeur. Vous allez créer une branch, faire une modification, partager un aperçu pour révision et publier vos modifications. + + **Prérequis** + + - L'accès à l'éditeur sur [app.mintlify.com](https://app.mintlify.com). Consultez [Éditeur web](/fr/editor) pour une visite de l'interface. + - Le rôle **administrateur** ou **éditeur**. Les visiteurs peuvent modifier sur une branch et laisser des [commentaires et suggestions](/fr/editor/collaborate), mais ne peuvent ni publier ni demander une révision. Consultez [Rôles](/fr/dashboard/roles). + + Une branch est une copie temporaire de votre contenu. C'est là que vous effectuez vos modifications sans affecter votre site publié. Vous pouvez fusionner une branch dans votre site publié ou l'abandonner en toute sécurité si vous choisissez de ne pas appliquer les modifications. @@ -21,6 +28,8 @@ Ce tutoriel vous guide à travers une mise à jour de contenu complète avec l' 1. Cliquez sur **New branch**. L'éditeur bascule vers votre nouvelle branch. Toutes les modifications que vous effectuez ne sont présentes que sur la branch, et elles sont commitées automatiquement sur la branch pendant que vous travaillez. Elles n'apparaissent sur votre site publié que si vous terminez le processus de publication. + + Pour abandonner une branch au lieu de la publier, survolez-la dans le menu des branches et cliquez sur **Delete branch**. Consultez [Supprimer une branch](/fr/guides/branches#delete-a-branch). Modifiez une page existante ou créez-en une nouvelle. diff --git a/fr/help-center/publish-button-disabled-invalid-mdx.mdx b/fr/help-center/publish-button-disabled-invalid-mdx.mdx index cde735fb9..29eddfe07 100644 --- a/fr/help-center/publish-button-disabled-invalid-mdx.mdx +++ b/fr/help-center/publish-button-disabled-invalid-mdx.mdx @@ -14,6 +14,17 @@ L'infobulle vous indique combien de pages ont des erreurs. La même erreur bloqu Tant qu'une page contient un MDX non valide ou un frontmatter YAML non valide, ces modifications restent locales à votre poste. Vos collègues qui modifient la même page ne reçoivent que du contenu valide, de sorte qu'une erreur de syntaxe que vous introduisez n'écrase pas leur travail. Consultez [Collaborer dans l'éditeur](/fr/editor/collaborate) pour comprendre comment l'édition en temps réel gère le contenu non valide. +
+ +## Localiser la page concernée + +
+ +Si l'infobulle indique une seule page en erreur, il s'agit généralement de celle que vous êtes en train de modifier. Si elle en indique plusieurs, ou si vous ne savez pas laquelle contient l'erreur, examinez chaque page que vous avez modifiée sur la branch : + +1. Cliquez sur **Publish** dans la barre d'outils pour ouvrir le menu de publication. Le menu liste tous les fichiers modifiés sur votre branch. +2. Ouvrez tour à tour chaque fichier modifié et cherchez les erreurs de parsing en mode source (voir ci-dessous). Les pages qui parsent correctement s'affichent normalement ; la page en erreur affiche l'erreur. +
## Corriger l'erreur manuellement @@ -24,11 +35,13 @@ Tant qu'une page contient un MDX non valide ou un frontmatter YAML non valide, c 2. Basculez en mode source avec Cmd + Shift + S (macOS) ou Ctrl + Shift + S (Windows). Le mode source met en évidence le MDX non valide et affiche l'erreur de parsing. 3. Corrigez la syntaxe. Une fois la page parsée, l'erreur disparaît et le bouton **Publish** redevient disponible. +Pour les erreurs de frontmatter, vérifiez que chaque valeur est du YAML valide : mettez entre guillemets les chaînes contenant des deux-points ou des caractères spéciaux, gardez une indentation cohérente et fermez toutes les guillemets. Consultez [Métadonnées de page](/fr/organize/pages#page-metadata) pour connaître les champs de frontmatter pris en charge. +
-### Corriger l'erreur avec l'agent +## Corriger l'erreur avec l'agent
1. Ouvrez le panneau de l'éditeur. -2. Demandez à l'agent de corriger tout MDX ou frontmatter YAML non valide. +2. Demandez à l'agent de corriger tout MDX ou frontmatter YAML non valide. Sans mention, l'agent utilise la page que vous avez ouverte comme contexte initial. Pour corriger des erreurs sur l'ensemble de la branch en une seule requête, demandez à l'agent de trouver et de réparer toutes les pages avec du MDX non valide. Consultez [Agent](/fr/editor/agent). diff --git a/zh/editor/tutorial.mdx b/zh/editor/tutorial.mdx index 2da6affa5..89438988b 100644 --- a/zh/editor/tutorial.mdx +++ b/zh/editor/tutorial.mdx @@ -6,6 +6,13 @@ keywords: ["editor", "tutorial", "branch", "publish"] 本教程将引导你使用编辑器完成一次完整的内容更新。你将创建分支、进行更改、分享预览以供审阅，然后发布你的更改。 + + **前置条件** + + - 可以访问 [app.mintlify.com](https://app.mintlify.com) 上的编辑器。参见[Web 编辑器](/zh/editor)了解界面导览。 + - 具备**管理员**或**编辑者**角色。访问者可以在分支上编辑并留下[评论和建议](/zh/editor/collaborate)，但不能发布或请求审阅。参见[角色](/zh/dashboard/roles)。 + + 分支是你内容的临时副本。你可以在其中进行更改，而不会影响你的线上站点。你可以把分支合并到线上站点，也可以在决定不进行更改时安全地丢弃它。 @@ -21,6 +28,8 @@ keywords: ["editor", "tutorial", "branch", "publish"] 1. 点击 **New branch**。 编辑器会切换到你的新分支。你所做的任何更改都只在该分支上，并在你工作时自动提交到该分支。只有在你完成发布流程后，它们才会出现在你的线上站点上。 + + 如果想丢弃分支而不是发布它，在分支菜单中将鼠标悬停在分支上并点击 **Delete branch**。参见[删除分支](/zh/guides/branches#delete-a-branch)。 编辑现有页面或创建新页面。 diff --git a/zh/help-center/publish-button-disabled-invalid-mdx.mdx b/zh/help-center/publish-button-disabled-invalid-mdx.mdx index 14e27aa70..aa34ae65f 100644 --- a/zh/help-center/publish-button-disabled-invalid-mdx.mdx +++ b/zh/help-center/publish-button-disabled-invalid-mdx.mdx @@ -14,6 +14,17 @@ keywords: ["publish disabled", "fix invalid MDX before publishing", "invalid MDX 当某个页面存在无效的 MDX 或无效的 frontmatter YAML 时，那些编辑仅保留在你本地。协作编辑同一页面的同事只会收到有效内容，因此你引入的语法错误不会覆盖他们的工作。有关实时编辑如何处理无效内容的说明，请参阅[在编辑器中协作](/zh/editor/collaborate)。 +
+ +## 查找受影响的页面 + +
+ +如果提示只显示一个损坏的页面，通常就是你当前正在编辑的那一个。如果显示多个，或者你不确定是哪个页面有错误，请检查你在分支上更改过的每个页面： + +1. 点击工具栏中的 **Publish** 打开发布菜单。菜单会列出你分支上所有已更改的文件。 +2. 依次打开每个已更改的文件，并在 source 模式下查找解析错误（见下文）。能够正常解析的页面会正常显示；出错的页面会显示错误。 +
## 手动修复错误 @@ -24,11 +35,13 @@ keywords: ["publish disabled", "fix invalid MDX before publishing", "invalid MDX 2. 使用 Cmd + Shift + S（macOS）或 Ctrl + Shift + S（Windows）切换到 source 模式。source 模式会高亮显示无效的 MDX 并展示解析错误。 3. 修复语法。页面能够解析后，错误即会消失，**Publish** 按钮也会重新可用。 +对于 frontmatter 错误，请检查每个值都是有效的 YAML：为包含冒号或特殊字符的字符串加上引号，保持缩进一致，并关闭所有引号。有关支持的 frontmatter 字段，请参阅[页面元数据](/zh/organize/pages#page-metadata)。 +
-### 使用智能体修复错误 +## 使用智能体修复错误
1. 打开编辑器面板。 -2. 提示智能体修复所有无效的 MDX 或 frontmatter YAML。 +2. 提示智能体修复所有无效的 MDX 或 frontmatter YAML。如果不进行提及，智能体会以你打开的页面作为初始上下文。若要通过一次提示修复分支上的所有错误，请让智能体查找并修复所有存在无效 MDX 的页面。参见[智能体](/zh/editor/agent)。 From 9aadc880f6a757724847fcb897e5130792afac51 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 23 Sep 2026 11:00:45 -0700 Subject: [PATCH 3/4] Apply suggestion from @ethanpalm --- editor/tutorial.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/editor/tutorial.mdx b/editor/tutorial.mdx index 0d57247c1..603790efb 100644 --- a/editor/tutorial.mdx +++ b/editor/tutorial.mdx @@ -9,7 +9,6 @@ This tutorial walks you through a complete content update using the editor. You' **Prerequisites** - - Access to the editor at [app.mintlify.com](https://app.mintlify.com). See [Web editor](/editor) for a tour of the interface. - The **admin** or **editor** role. Viewers can edit on a branch and leave [comments and suggestions](/editor/collaborate), but they can't publish or request review. See [Roles](/dashboard/roles). From 0e213205fae6a64284b66f069da71c6b08859753 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 23 Sep 2026 11:01:27 -0700 Subject: [PATCH 4/4] Apply suggestion from @ethanpalm --- editor/tutorial.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/editor/tutorial.mdx b/editor/tutorial.mdx index 603790efb..71d0def8e 100644 --- a/editor/tutorial.mdx +++ b/editor/tutorial.mdx @@ -7,9 +7,7 @@ keywords: ["editor", "tutorial", "branch", "publish"] This tutorial walks you through a complete content update using the editor. You'll create a branch, make a change, share a preview for review, and publish your changes. - **Prerequisites** - - - The **admin** or **editor** role. Viewers can edit on a branch and leave [comments and suggestions](/editor/collaborate), but they can't publish or request review. See [Roles](/dashboard/roles). +You must have the **admin** or **editor** role to complete all the steps in this tutorial. Viewers can edit on a branch and leave [comments and suggestions](/editor/collaborate), but they can't publish or request review. See [Roles](/dashboard/roles).