diff --git a/docs.json b/docs.json index ea02ceb9d8..eec606e044 100644 --- a/docs.json +++ b/docs.json @@ -89,13 +89,16 @@ "root": "editor/index", "pages": [ "editor/tutorial", + "editor/collaborate", "editor/branching-and-publishing", "editor/live-preview", + "editor/share-a-preview", "editor/pages", "editor/navigation", "editor/keyboard-shortcuts", "editor/configurations", - "editor/settings" + "editor/settings", + "editor/git-essentials" ] }, "create/text", diff --git a/editor/branching-and-publishing.mdx b/editor/branching-and-publishing.mdx index a987e721d2..f829e9dffd 100644 --- a/editor/branching-and-publishing.mdx +++ b/editor/branching-and-publishing.mdx @@ -79,34 +79,7 @@ If there are no pending changes, the editor disables the publish and save action ## Preview your changes -Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL where your changes render exactly as they look when published. - -### Access and share a preview - -1. Click **Publish** in the editor toolbar. -1. In the publish menu, click the preview URL. The URL format is `organization-branch-name.mintlify.app`. - - Preview URL emphasized in the publish menu. - Preview URL emphasized in the publish menu. - - -Copy the URL and send it to reviewers. The preview updates automatically each time you save to the branch. - -### Restrict access to previews - -Preview URLs are publicly accessible by default. To restrict access to members of your Mintlify organization, enable preview authentication in the [Add-ons](https://app.mintlify.com/products/addons) page of your dashboard. - -### Share editor links - -To invite a teammate to a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session. - -The URL format is: - -```text -https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath} -``` - -For example: `https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx` +Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL where your changes render how they look when published. See [Share a preview](/editor/share-a-preview) for how to access, share, and restrict access to preview deployments. ## Review and merge pull requests @@ -146,19 +119,9 @@ When you publish, you can enter a commit message before confirming. If you leave ## Resolve conflicts -Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. For example, when you and a teammate edited the same lines in a file or moved a file to different locations. - -The editor displays a warning when conflicts block publishing. Follow the prompts to choose which version of each conflicting section to keep. - -## 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. +Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. For example, if you and a teammate both edited the same lines, or a file was moved in two different directions. -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. +When conflicts block publishing, the editor shows an error and prevents the publish from completing. Resolve conflicts by switching to your Git provider (GitHub or GitLab) and merging or rebasing the conflicting branches there, then return to the editor to publish. ## Git sync diff --git a/editor/collaborate.mdx b/editor/collaborate.mdx index 5d9c0c95e8..2988e43eb7 100644 --- a/editor/collaborate.mdx +++ b/editor/collaborate.mdx @@ -1,8 +1,8 @@ --- title: "Collaborate in the web editor" sidebarTitle: "Collaborate" -description: "Edit documentation with your team using real-time collaboration, live cursors, shareable editor links, branches, and pull request review workflows." -keywords: ["editor", "collaboration", "real-time", "live editing", "branches", "pull requests", "preview deployments", "share links"] +description: "Edit documentation with your team using real-time collaboration, live cursors, an AI agent chat panel, shareable editor links, branches, and pull request review workflows." +keywords: ["editor", "collaboration", "real-time", "live editing", "branches", "pull requests", "preview deployments", "share links", "agent", "assistant"] --- Collaborate with your team on documentation using real-time editing and branch-based workflows. @@ -11,14 +11,7 @@ Collaborate with your team on documentation using real-time editing and branch-b Multiple people can edit the same page at the same time. Changes from each person appear for everyone on the page. -To collaborate on a page in real time, share the editor link for that page with your teammates. See [Share editor links](#share-editor-links) below. - - - Web editor showing real-time collaboration with multiple cursors - Web editor showing real-time collaboration with multiple cursors - - -### How real-time editing works +To collaborate on a page in real time, share the editor link for that page with your teammates. See [Share a preview](/editor/share-a-preview#share-editor-links) for the URL format. When multiple team members edit the same branch, changes sync in real-time. Page content, navigation structure, and site configuration updates appear automatically for all collaborators without refreshing. @@ -27,9 +20,36 @@ When multiple team members edit the same branch, changes sync in real-time. Page - Undo only affects your own changes—undoing won't revert another person's edits. - If you lose your network connection, your edits save locally and sync when you reconnect. +## Chat with the agent in the editor + +The agent panel lets you chat with the [Mintlify agent](/agent) directly inside the editor. Open it by clicking the agent icon in the left sidebar. The panel sits to the left of the file explorer so you can chat and navigate files at the same time. + +### Start a session + +Type a prompt in the chat input and press Enter. The agent reads your docs and makes edits on the current branch. + +### Attach context + +Click the paperclip icon in the chat input to attach context to your message. You can attach: + +- **Files** — any file from your repository +- **Pages** — specific documentation pages the agent should read or edit +- **Divisions** — a tab, anchor, or other navigation section +- **Inline text** — paste text directly into the attachment field + +Attaching context focuses the agent on the right part of your docs without requiring you to describe it in your prompt. + +### Review per-session diffs + +After the agent makes changes, a diff summary appears in the chat panel showing the changes. Click any file in the diff summary to navigate to that page in the editor. + +### Leave feedback + +Use the thumbs up and thumbs down buttons in the chat panel to rate the agent's response. This helps improve future results. + ## See the agent's edits in real time -When the [Mintlify agent](/agent) edits a page through the API or MCP, it appears in the web editor like any other collaborator. If you have the page open on the same branch, you see the agent's avatar and name at the top of the editor and a live cursor at the location of its most recent edit. +When the [Mintlify agent](/agent) edits a page through the API, MCP, or the agent panel, it appears in the web editor like any other collaborator. If you have the page open on the same branch, you see the agent's avatar and name at the top of the editor and a live cursor at the location of its most recent edit. Use this to: @@ -39,6 +59,10 @@ Use this to: The agent's cursor clears automatically a short time after the agent finishes editing. +## Send content to the assistant + +To send highlighted content to the [assistant](/assistant), select text in the editor. A floating toolbar appears above the selection. Click **Add to Assistant**. The selected content attaches to a new assistant conversation so you can ask questions or request changes without switching context. + ## Branch-based collaboration Use branches to work on documentation updates in parallel without affecting your live site. If you aren't familiar with Git, see [Git essentials for the web editor](/editor/git-essentials). @@ -68,33 +92,6 @@ Use pull requests to propose changes and collaborate with your team before mergi -## Preview deployments - -Preview deployments create temporary URLs where you can see your rendered changes before they go live. Use preview deployments to gather feedback on your changes. - -Every time you publish changes to a branch, the preview deployment updates automatically. - -### Access preview deployments - -1. Click **Publish** in the editor toolbar. -2. Click the preview URL to open the preview deployment in a new tab. The URL format is `organization-branch-name.mintlify.app`. - -### Share previews - -Share the preview deployment URL with team members to gather feedback. Previews update automatically when you publish additional changes. - -### Preview authentication - -Preview URLs are publicly accessible by default. Enable preview authentication in the [Add-ons](https://app.mintlify.com/products/addons) page of your dashboard to restrict access to authenticated organization members. - -## Share editor links - -Share a direct link to a specific page in the editor with your teammates. Use editor links to collaborate on updates in real time or point teammates to a specific page. - -The editor URL updates automatically as you navigate between pages. Copy the URL from your browser's address bar to share it with teammates who have access to the editor. - -The URL format is: `https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}` - -For example, `https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx` opens `quickstart.mdx` on the `main` branch. +## Share previews and editor links -Anyone with access to your Mintlify organization can use the link to open the file directly in the editor. +See [Share a preview](/editor/share-a-preview) for how to share preview deployment URLs and editor links with your team. diff --git a/editor/live-preview.mdx b/editor/live-preview.mdx index 881153291b..d4b5deac22 100644 --- a/editor/live-preview.mdx +++ b/editor/live-preview.mdx @@ -4,11 +4,11 @@ description: "Preview your documentation site in real time as you edit, with con keywords: ["editor", "preview", "live preview"] --- -Preview your site while you edit. Live previews render pages exactly as they look when published, and update as you make changes to content, navigation, and configuration. +Live preview renders your documentation site in a separate tab and updates as you make changes. ## Open live preview -Click the live preview button in the toolbar to open a live preview in a new tab. +Click the live preview button in the editor toolbar to open live preview in a new tab. live preview button in the toolbar to open a live /> +Live preview reflects the current branch. Changes to content, navigation structure, and `docs.json` configuration all render immediately. Keep both tabs open to edit and preview side by side. + - Live preview is only available for public documentation. + Live preview is only available for public documentation. If your site requires authentication, use a [preview deployment](/editor/share-a-preview) instead. ## Live preview versus preview deployments | | Live preview | Preview deployment | |---|---|---| -| **Speed** | Instant | Requires a build | -| **Access** | Local URL | Shareable URL | -| **Use when** | Reviewing changes while editing | Sharing with your team for review | +| **Updates** | Instant, as you type | Requires a save to the branch | +| **URL** | Local to your browser session | Shareable with anyone | +| **Use when** | Checking your own changes while editing | Sharing with teammates or reviewing on another device | | **Availability** | While the editor is open | As long as the branch exists | - -Use live preview for immediate feedback while editing. When you need to share changes with your team or test on a different device, use a [preview deployment](/editor/branching-and-publishing#preview-your-changes). diff --git a/editor/pages.mdx b/editor/pages.mdx index 4bb67a3731..a73f6330cf 100644 --- a/editor/pages.mdx +++ b/editor/pages.mdx @@ -6,18 +6,42 @@ keywords: ["editor", "content", "pages", "files", "create", "edit", "media", "im ## Navigate files -Browse pages in the **Navigation** tab of the left panel. Click a page to open it. Click the search icon or press Cmd + K (macOS) or Ctrl + K (Windows) to search by filename or page content. +The left panel has two views: **Navigation** and **Files**. + +**Navigation** shows your documentation sidebar structure. Click a page to open it. + +**Files** shows the full file tree of your repository, including files that aren't in your navigation. Click any file to open it. Click the search icon or press Cmd + K (macOS) or Ctrl + K (Windows) to search by filename or page content. + +The browser tab title updates automatically to show the name of the file you have open, making it easier to tell pages apart when you have multiple tabs open. The web editor treats API specification files (OpenAPI and AsyncAPI) as read-only. To update a spec file, edit it in your preferred code editor and push the changes to your documentation repository. +## Manage files and folders + +Use the file tree to organize your content: + +- **Create a folder**: Click the new folder button at the top of the file tree, or right-click an existing folder and select **New folder**. +- **Rename a file or folder**: Right-click the item and select **Rename**. +- **Open unlisted files**: Click any Markdown or media file in the tree to open it, even if it isn't included in your navigation. + +Files you open from the tree that aren't in your navigation are unlisted — they exist in your repository but won't appear in your published documentation sidebar. + ## Create new pages +### Add a page to navigation + 1. Click the plus button in the navigation element where you want to add a page. 1. Click **Add a page**. 1. Enter a filename. The editor adds the `.mdx` extension automatically. +### Create an unlisted page + +Unlisted pages exist in your repository but don't appear in navigation. They're useful for draft content, reusable snippets, or pages you plan to add to navigation later. + +To create an unlisted page, right-click any folder in the file tree and select **New file**. Enter a filename and the editor creates the page without adding it to navigation. You can add it to navigation later from the **Navigation** tab. + ## Edit content Switch between visual and Markdown mode with the toggle in the toolbar. diff --git a/editor/settings.mdx b/editor/settings.mdx index 45b38dfadf..8894beacf5 100644 --- a/editor/settings.mdx +++ b/editor/settings.mdx @@ -9,7 +9,7 @@ The web editor has two layers of settings: - **Your settings** apply only to you and control how the editor's AI assists with your edits. - **Publishing settings** apply to everyone on a deployment and shape what happens when you commit changes and turn them into pull requests. -You can configure both from the **Settings** menu in the editor. +You can configure both from the settings panel. To open it, click the settings icon in the editor toolbar. The panel consolidates all per-editor preferences in one place. ## AI instructions @@ -35,10 +35,9 @@ Keep instructions short and specific. The AI follows them on every request, so v ### Configure AI instructions -1. Open the editor and click your avatar in the toolbar. -2. Select **Settings**. -3. In the **AI instructions** field, enter the guidance you want the AI to follow. -4. Save your changes. +1. Open the editor and click the settings icon in the toolbar. +2. In the **AI instructions** field, enter the guidance you want the AI to follow. +3. Save your changes. Example: diff --git a/editor/share-a-preview.mdx b/editor/share-a-preview.mdx index 0060a2a8a3..499152efb0 100644 --- a/editor/share-a-preview.mdx +++ b/editor/share-a-preview.mdx @@ -6,16 +6,21 @@ keywords: ["editor", "preview", "preview deployment", "share", "collaboration", ## Preview deployments -Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL that renders your changes exactly as they look when published. Use it to review your work or collect feedback before merging. +Every time you save changes to a feature branch, Mintlify builds a preview deployment — a temporary URL that renders your changes exactly as they look when published. Use it to review your work or collect feedback before merging. ### Access your preview 1. Click **Publish** in the editor toolbar. 1. In the publish menu, click the preview URL. The URL format is `organization-branch-name.mintlify.app`. + + Preview URL in the publish menu. + Preview URL in the publish menu. + + ### Share your preview -Copy the preview URL and send it to reviewers. The preview updates automatically each time you save to the branch. +Copy the preview URL and send it to reviewers. The preview updates automatically each time you save to the branch, so reviewers always see your latest changes at the same URL. ### Restrict access to previews @@ -23,13 +28,12 @@ Preview URLs are publicly accessible by default. To restrict access to members o ## Share editor links -To invite a teammate to view or edit a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session. +To invite a teammate to view or edit a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session on the same branch. The URL format is: -``` +```text https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath} ``` For example: `https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx` -