Document diff view in the web editor

editor/pages.mdx

@@ -28,7 +28,7 @@
 Switch between visual and Markdown mode with the toggle in the toolbar. The web editor saves your changes when switching modes.
 
 <Note>
   API specification files (OpenAPI and AsyncAPI) are read-only in the web editor. You can view their contents but cannot edit them directly. To update a spec file, edit it using your preferred code editor and push the changes to your documentation repository.
 </Note>
 
 <Frame>
@@ -55,11 +55,11 @@
 - **Add images**: Use the image component from the <kbd>/</kbd> menu or type <kbd>/image</kbd>.
 - **Add videos**: Type <kbd>/video</kbd> to upload or select a video.
 - **Add embedded content**: Type <kbd>/youtube</kbd> or <kbd>/loom</kbd> to embed videos, or <kbd>/embed</kbd> for custom HTML. See [Add media](/editor/media) for details.
 - **Add Mermaid diagrams**: Type <kbd>/mermaid</kbd> to insert a Mermaid diagram with an interactive preview, zoom/pan controls, and code editor.
 - **Add snippets**: Type <kbd>/snippet</kbd> to search for and insert a reusable snippet. The editor adds the required import statement automatically.
 - **Add math equations**: Type <kbd>/inline-math</kbd> for an inline LaTeX equation or <kbd>/block-math</kbd> for a centered block equation. [Enable LaTeX](/editor/configurations) in your site settings first.
 - **Add prompt blocks**: Type <kbd>/prompt</kbd> to insert an AI prompt template with copy actions.
 - **Edit tables**: When your cursor is inside a table, use the floating toolbar to add or remove rows and columns, or merge cells.
 - **Insert links**: Select text and press <kbd>Cmd</kbd> + <kbd>K</kbd>, or drag a page from the navigation tree into the editor to create a link with the page title.
 
 See [Components](/components) for the complete list of available components.
@@ -74,6 +74,20 @@
 
 See [Format text](/create/text) and [Format code](/create/code) for more information on MDX syntax.
 
+### Diff view
+
+Review your unpublished changes before publishing by comparing your current edits against the last published version. Diff view is read-only — exit it to resume editing.
+
+To enter diff view, click a changed file in the publish popover. The editor switches to diff view and highlights the differences between your draft and the published version. If you are in visual mode, the editor shows a visual diff. If you are in Markdown mode, the editor shows a Markdown diff.
+
+While in diff view, you can:
+
+- **Switch diff modes**: Use the mode toggle to switch between visual diff and Markdown diff.
+- **Navigate between changed files**: Click other files in the publish popover to compare them.
+- **Exit diff view**: Click the <Icon icon="xmark" /> button next to the mode toggle to return to editing.
+
+The diff view updates automatically when the published version changes, so you always see an accurate comparison.
+
 ## Configure pages
 
 Configure page settings to control how pages appear in navigation, search results, and your site layout.
@@ -99,7 +113,7 @@
 
 - **Title**: Set the main heading. Appears in navigation, browser tabs, and search results.
 - **Slug**: Set the URL path for the page. The slug defaults to the path relative to your repository root without the file extension. For example, `guides/getting-started.mdx` becomes `guides/getting-started`. Changing the slug renames and moves the file to match the new path.
 - **Sidebar title**: Display shorter text in navigation when the full title is too long for the sidebar.
 - **Icon**: Add a visual marker next to the page to help users identify it quickly.
 - **External URL**: Link to an external site instead of a page. Use this to add external resources to your navigation.
 

editor/publish.mdx

@@ -54,6 +54,10 @@ When you work on a feature branch, save changes to the branch.
 
 To discard changes, click **Undo changes** beside a filename in the files changed dropdown.
 
+## Review changes
+
+Click a changed file in the publish popover to open it in [diff view](/editor/pages#diff-view). The editor highlights the differences between your draft and the published version so you can review your edits before publishing. Click additional files in the popover to compare them without leaving diff view.
+
 ## Publish your changes
 
 Click **Publish** in the toolbar. Depending on your workflow, your changes deploy immediately or create a pull request for you to merge in your Git provider. If you are on a feature branch, save your changes before publishing.