mintlify · mintlify · May 19, 2026 · May 19, 2026
diff --git a/editor/branching-and-publishing.mdx b/editor/branching-and-publishing.mdx
@@ -4,7 +4,7 @@
 keywords: ["editor", "branch", "publish", "pull request", "preview", "git", "merge", "deploy"]
 ---

 The web editor autosaves everything as you type, but your changes are only live when you choose to publish them. 

 What happens when you publish depends on two things: **which branch you're on** and **whether that branch requires pull requests**.

@@ -124,7 +124,7 @@

 ### Approve pull requests from the editor

 For GitHub repositories, reviewers can approve open pull requests in the editor. When a pull request is open, an **Approve pull request** button appears in the review panel if your account has permission to review it. Click **Approve pull request** when the changes are ready to be merged. The review status updates to **Approved** and the **Merge and publish** action becomes available.

 The approve action is not available for draft pull requests, pull requests you have already approved, or GitLab merge requests. Click **Open in GitLab** to approve a merge request in GitLab.

@@ -140,6 +140,10 @@
 
 Only one publish can happen at a time per branch. If another team member publishes to the same branch, wait for the current publish to complete before trying again.
 
+### Unapplied `docs.json` changes
+
+If `docs.json` has edits that haven't been applied, the publish menu shows a **docs.json has unapplied changes** banner and disables the publish actions. Click the banner to open `docs.json`, then apply or discard the edits to unblock publishing. See [Edit docs.json directly](/editor/configurations#edit-docs-json-directly).
+
 ### Commit messages
 
 When you publish, you can enter a commit message before confirming. If you leave it blank, the editor generates a message based on the files changed.
@@ -152,13 +156,13 @@

 ## Collaborate in real time

 When multiple people open the same page on the same branch, they edit together in real time. Each person's cursor and edits are visible to everyone, with avatars shown in the toolbar.

 - Changes from all collaborators merge automatically. Two people editing the same section won't create conflicts.
 - Undo only affects your own edits.
 - If you lose your connection, edits save locally and sync when you reconnect.

 When the [Mintlify agent](/agent) edits a page through the API or MCP, it appears in the editor like any other collaborator. You see the agent's avatar in the toolbar and a live cursor at its most recent edit location. The cursor clears automatically after the agent finishes.

 ## Git sync


diff --git a/editor/configurations.mdx b/editor/configurations.mdx
@@ -139,3 +139,22 @@
 - **Menu drilldown**: Enable or disable auto-navigating to the first page when a user clicks a navigation group.
 - **Timestamps**: Show "Last modified on [date]" on all pages.
 - **SEO indexing**: Choose whether to index hidden pages for search engines.
+
+## Edit `docs.json` directly
+
+For configuration options that aren't surfaced in the **Configurations** panel, open `docs.json` from the file tree and edit it as raw JSON. Manual edits and changes from the **Configurations** panel stay in sync, so you can switch between them on the same branch.
+
+When you open `docs.json`, a toolbar appears above the editor with **Apply changes** and **Discard** actions:
+
+- **Apply changes**: Validates your JSON and writes it to the working copy of `docs.json` on the current branch. The navigation sidebar updates immediately to reflect the new structure. Press <kbd>Cmd</kbd> + <kbd>S</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>S</kbd> (Windows) to apply.
+- **Discard**: Reverts the file to the last applied version.
+
+If your edit contains invalid JSON, the toolbar turns red and shows the line number of the syntax error. **Apply changes** stays disabled until the JSON parses successfully.
+
+<Note>
+  Applying changes does not publish them. To deploy your edits to your live site, use **Publish** in the toolbar. See [Branching and publishing](/editor/branching-and-publishing).
+</Note>
+
+<Warning>
+  The publish menu blocks publishing while `docs.json` has unapplied edits and shows a **docs.json has unapplied changes** banner. Click the banner to open the file, then apply or discard your changes before publishing.
+</Warning>
diff --git a/editor/keyboard-shortcuts.mdx b/editor/keyboard-shortcuts.mdx
@@ -52,7 +52,7 @@
 | **Add link** to selected text | <kbd>Cmd</kbd> + <kbd>K</kbd> | <kbd>Ctrl</kbd> + <kbd>K</kbd> |
 | **Add line break** | <kbd>Cmd</kbd> + <kbd>Enter</kbd> | <kbd>Ctrl</kbd> + <kbd>Enter</kbd> |
 | **Component menu** | <kbd>/</kbd> | <kbd>/</kbd> |
 | **Emoji picker** | <kbd>:</kbd> + keyword | <kbd>:</kbd> + keyword |

 ### Smart substitutions

@@ -93,6 +93,14 @@

 | Command | macOS | Windows |
 | :--- | :--- | :--- |
 | **Add cursor** | <kbd>Option</kbd> + Click | <kbd>Alt</kbd> + Click |
 | **Add cursor above** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↑</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↑</kbd> |
 | **Add cursor below** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↓</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↓</kbd> |
+
+## `docs.json` editor
+
+Use these shortcuts when editing `docs.json` directly. See [Edit docs.json directly](/editor/configurations#edit-docs-json-directly).
+
+| Command | macOS | Windows |
+| :--- | :--- | :--- |
+| **Apply changes** | <kbd>Cmd</kbd> + <kbd>S</kbd> | <kbd>Ctrl</kbd> + <kbd>S</kbd> |
diff --git a/editor/navigation.mdx b/editor/navigation.mdx
@@ -1,16 +1,16 @@
 ---
 title: "Organize navigation"
 description: "Reorder pages, add groups, and manage your documentation sidebar structure using drag-and-drop in the Mintlify web editor — no docs.json edits needed."
 keywords: ["editor", "navigation", "sidebar", "structure"]
 ---
 
-Use the navigation sidebar to organize your documentation. Changes you make in the editor sync to your repository when you publish—you don't need to edit `docs.json` manually.
+Use the navigation sidebar to organize your documentation. Changes you make in the editor sync to your repository when you publish—you don't need to edit `docs.json` manually. If you prefer to edit the file directly, see [Edit docs.json directly](/editor/configurations#edit-docs-json-directly).
 
 ## Add navigation elements
 
 Click **Add new** at the bottom of the navigation tree to add a new element at the root level. To add an element nested inside another, click the <Icon icon="plus" /> plus button next to that element.

 After creating an element, drag and drop it to reorder or nest it. Hover over an element and click the gear icon to configure its properties.

 Right-click a **page** to open its settings or delete it.

@@ -24,15 +24,15 @@

 Choose the right structure for your content:

 - **Pages** — Individual documentation files. The core building block of navigation.
 - **Groups** — Collapsible sections that cluster related pages together. Can nest within other groups.
 - **Tabs** — Top-level sections with horizontal navigation at the top of your site. Use tabs when you have distinct areas like API Reference and Guides.
 - **Anchors** — Persistent items at the top of your sidebar. Useful for quick access to external resources or top-level sections. Can be global to appear on every page.
 - **Dropdowns** — Expandable menus at the top of your sidebar. A lighter alternative to tabs for multiple related sections.
 - **Menus** — Dropdown navigation items within a tab for direct links to specific pages.
 - **Products** — A switcher for multiple distinct product documentation sets, each with its own navigation structure.
 - **Versions** — A switcher for multiple simultaneous documentation versions.
 - **Languages** — A switcher for documentation in multiple languages.

 ## Configure elements

@@ -40,5 +40,5 @@

 - **Title**: The label shown in the sidebar.
 - **Icon**: A visual marker next to the label.
 - **Tag**: A badge like "NEW" or "BETA" to highlight the item.

diff --git a/es/editor/configurations.mdx b/es/editor/configurations.mdx
@@ -123,4 +123,24 @@ Realiza el seguimiento del comportamiento de los visitantes con:
 Integraciones adicionales:
 
 * **Telemetry**: Activa o desactiva la telemetría de uso
-* **Cookies**: Define pares personalizados de key y value de cookies
+* **Cookies**: Define pares personalizados de key y value de cookies
+<div id="edit-docs-json-directly">
+  ## Editar `docs.json` directamente
+</div>
+
+Para las opciones de configuración que no aparecen en el panel **Configurations**, abre `docs.json` desde el árbol de archivos y edítalo como JSON sin formato. Las ediciones manuales y los cambios realizados desde el panel **Configurations** se mantienen sincronizados, por lo que puedes alternar entre ambos en la misma branch.
+
+Cuando abres `docs.json`, aparece una barra de herramientas encima del editor con las acciones **Apply changes** y **Discard**:
+
+- **Apply changes**: Valida tu JSON y lo escribe en la copia de trabajo de `docs.json` en la branch actual. La barra lateral de navegación se actualiza de inmediato para reflejar la nueva estructura. Presiona <kbd>Cmd</kbd> + <kbd>S</kbd> (macOS) o <kbd>Ctrl</kbd> + <kbd>S</kbd> (Windows) para aplicar.
+- **Discard**: Revierte el archivo a la última versión aplicada.
+
+Si tu edición contiene JSON no válido, la barra de herramientas se vuelve roja y muestra el número de línea del error de sintaxis. **Apply changes** permanece deshabilitado hasta que el JSON se analice correctamente.
+
+<Note>
+  Aplicar los cambios no los publica. Para implementar tus ediciones en tu sitio en producción, usa **Publish** en la barra de herramientas. Consulta [Publicar](/es/editor/publish).
+</Note>
+
+<Warning>
+  El menú de publicación bloquea la publicación mientras `docs.json` tenga ediciones sin aplicar y muestra un banner **docs.json has unapplied changes**. Haz clic en el banner para abrir el archivo, luego aplica o descarta tus cambios antes de publicar.
+</Warning>
diff --git a/es/editor/keyboard-shortcuts.mdx b/es/editor/keyboard-shortcuts.mdx
@@ -117,4 +117,13 @@ El modo Markdown usa el editor Monaco, que es compatible con los atajos de tecla
 | :--- | :--- | :--- |
 | **Agregar cursor** | <kbd>Option</kbd> + clic | <kbd>Alt</kbd> + clic |
 | **Agregar cursor encima** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↑</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↑</kbd> |
-| **Agregar cursor debajo** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↓</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↓</kbd> |
+| **Agregar cursor debajo** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↓</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↓</kbd> |
+<div id="docs-json-editor">
+  ## Editor de `docs.json`
+</div>
+
+Usa estos atajos al editar `docs.json` directamente. Consulta [Editar docs.json directamente](/es/editor/configurations#edit-docs-json-directly).
+
+| Comando | macOS | Windows |
+| :--- | :--- | :--- |
+| **Aplicar cambios** | <kbd>Cmd</kbd> + <kbd>S</kbd> | <kbd>Ctrl</kbd> + <kbd>S</kbd> |
diff --git a/es/editor/navigation.mdx b/es/editor/navigation.mdx
@@ -4,7 +4,7 @@ description: "Organiza la estructura de tu sitio de documentación con el editor
 keywords: ["editor", "navegación", "barra lateral", "estructura"]
 ---
 
-Usa la barra lateral de navegación para organizar tu documentación. Los cambios que realices en el árbol de navegación del editor web aparecerán en la barra lateral de navegación de tu sitio y se sincronizarán con tu archivo de configuración `docs.json`.
+Usa la barra lateral de navegación para organizar tu documentación. Los cambios que realices en el árbol de navegación del editor web aparecerán en la barra lateral de navegación de tu sitio y se sincronizarán con tu archivo de configuración `docs.json`. Si prefieres editar el archivo directamente, consulta [Editar docs.json directamente](/es/editor/configurations#edit-docs-json-directly).
 
 <div id="add-navigation-elements">
   ## Agregar elementos de navegación

diff --git a/es/editor/publish.mdx b/es/editor/publish.mdx
@@ -93,6 +93,12 @@ Los conflictos se producen cuando intentas fusionar branches con cambios incompa
 * Tú y otra persona del equipo modifican las mismas líneas de un archivo en distintas branches.
 * Los archivos se mueven, renombran o eliminan en una branch, pero se modifican de otra forma en otra.
 
+<div id="unapplied-docs-json-changes">
+  ### Cambios sin aplicar en `docs.json`
+</div>
+
+Si `docs.json` tiene ediciones que no se han aplicado, el menú de publicación muestra un banner **docs.json has unapplied changes** y deshabilita las acciones de publicación. Haz clic en el banner para abrir `docs.json` y luego aplica o descarta las ediciones para desbloquear la publicación. Consulta [Editar docs.json directamente](/es/editor/configurations#edit-docs-json-directly).
+
 <div id="resolve-conflicts">
   ### Resolver conflictos
 </div>

diff --git a/fr/editor/configurations.mdx b/fr/editor/configurations.mdx
@@ -123,4 +123,25 @@ Suivez le comportement des visiteurs avec :
 Intégrations supplémentaires :
 
 * **Telemetry** : activer ou désactiver la télémétrie d&#39;utilisation
-* **Cookies** : définir des paires clé/valeur de cookies personnalisées
+* **Cookies** : définir des paires clé/valeur de cookies personnalisées
+
+<div id="edit-docs-json-directly">
+  ## Modifier `docs.json` directement
+</div>
+
+Pour les options de configuration qui n'apparaissent pas dans le panneau **Configurations**, ouvrez `docs.json` depuis l'arborescence de fichiers et modifiez-le sous forme de JSON brut. Les modifications manuelles et les changements effectués depuis le panneau **Configurations** restent synchronisés, vous pouvez donc passer de l'un à l'autre sur la même branche.
+
+Lorsque vous ouvrez `docs.json`, une barre d'outils apparaît au-dessus de l'éditeur avec les actions **Apply changes** et **Discard** :
+
+- **Apply changes** : Valide votre JSON et l'écrit dans la copie de travail de `docs.json` sur la branche actuelle. La barre latérale de navigation se met à jour immédiatement pour refléter la nouvelle structure. Appuyez sur <kbd>Cmd</kbd> + <kbd>S</kbd> (macOS) ou <kbd>Ctrl</kbd> + <kbd>S</kbd> (Windows) pour appliquer.
+- **Discard** : Restaure le fichier à la dernière version appliquée.
+
+Si votre modification contient un JSON invalide, la barre d'outils devient rouge et affiche le numéro de ligne de l'erreur de syntaxe. **Apply changes** reste désactivé jusqu'à ce que le JSON soit analysé correctement.
+
+<Note>
+  Appliquer les modifications ne les publie pas. Pour déployer vos modifications sur votre site en production, utilisez **Publish** dans la barre d'outils. Consultez [Publier](/fr/editor/publish).
+</Note>
+
+<Warning>
+  Le menu de publication bloque la publication tant que `docs.json` contient des modifications non appliquées et affiche une bannière **docs.json has unapplied changes**. Cliquez sur la bannière pour ouvrir le fichier, puis appliquez ou ignorez vos modifications avant de publier.
+</Warning>
diff --git a/fr/editor/keyboard-shortcuts.mdx b/fr/editor/keyboard-shortcuts.mdx
@@ -117,4 +117,13 @@ Le mode Markdown utilise l’éditeur Monaco, qui prend en charge les raccourcis
 | :--- | :--- | :--- |
 | **Ajouter un curseur** | <kbd>Option</kbd> + Clic | <kbd>Alt</kbd> + Clic |
 | **Ajouter un curseur au-dessus** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↑</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↑</kbd> |
-| **Ajouter un curseur en dessous** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↓</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↓</kbd> |
+| **Ajouter un curseur en dessous** | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>↓</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>↓</kbd> |
+<div id="docs-json-editor">
+  ## Éditeur `docs.json`
+</div>
+
+Utilisez ces raccourcis lors de la modification directe de `docs.json`. Consultez [Modifier docs.json directement](/fr/editor/configurations#edit-docs-json-directly).
+
+| Commande | macOS | Windows |
+| :--- | :--- | :--- |
+| **Appliquer les modifications** | <kbd>Cmd</kbd> + <kbd>S</kbd> | <kbd>Ctrl</kbd> + <kbd>S</kbd> |
diff --git a/fr/editor/navigation.mdx b/fr/editor/navigation.mdx
@@ -4,7 +4,7 @@ description: "Organisez la structure de votre site de documentation avec l’éd
 keywords: ["editor", "navigation", "sidebar", "structure"]
 ---
 
-Utilisez la barre latérale de navigation pour organiser votre documentation. Les modifications que vous effectuez dans l’arborescence de navigation de l’éditeur web apparaissent dans la barre latérale de navigation de votre site et sont synchronisées avec votre fichier de configuration `docs.json`.
+Utilisez la barre latérale de navigation pour organiser votre documentation. Les modifications que vous effectuez dans l’arborescence de navigation de l’éditeur web apparaissent dans la barre latérale de navigation de votre site et sont synchronisées avec votre fichier de configuration `docs.json`. Si vous préférez modifier le fichier directement, consultez [Modifier docs.json directement](/fr/editor/configurations#edit-docs-json-directly).
 
 <div id="add-navigation-elements">
   ## Ajouter des éléments de navigation

diff --git a/fr/editor/publish.mdx b/fr/editor/publish.mdx
@@ -93,6 +93,12 @@ Les conflits surviennent lorsque vous essayez de fusionner des branches contenan
 * Vous et un autre membre de l&#39;équipe modifiez les mêmes lignes dans un fichier sur des branches différentes.
 * Vous déplacez, renommez ou supprimez des fichiers dans une branche, mais les modifiez différemment dans une autre.
 
+<div id="unapplied-docs-json-changes">
+  ### Modifications non appliquées de `docs.json`
+</div>
+
+Si `docs.json` contient des modifications qui n'ont pas été appliquées, le menu de publication affiche une bannière **docs.json has unapplied changes** et désactive les actions de publication. Cliquez sur la bannière pour ouvrir `docs.json`, puis appliquez ou ignorez les modifications pour débloquer la publication. Consultez [Modifier docs.json directement](/fr/editor/configurations#edit-docs-json-directly).
+
 <div id="resolve-conflicts">
   ### Résoudre les conflits
 </div>