diff --git a/changelog.mdx b/changelog.mdx index d4d40b8899..8c2e23852b 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -954,7 +954,7 @@ noindex: true ## Web editor improvements - - Added [shareable preview links](/editor/collaborate#share-previews) from the editor toolbar. + - Added [shareable preview links](/editor/branching-and-publishing#access-and-share-a-preview) from the editor toolbar. - Updated [publishing workflow](/editor/branching-and-publishing) to support one-click publishing or creating pull requests. - Working in the web editor no longer requires you to sign in with GitHub. diff --git a/docs.json b/docs.json index 2c19ab6b92..7b39c7ce2d 100644 --- a/docs.json +++ b/docs.json @@ -85,17 +85,18 @@ "pages": [ { "group": "Editor", - "tag": "New", - "root": "editor/index", "pages": [ + "editor/index", "editor/tutorial", - "editor/branching-and-publishing", - "editor/live-preview", + "editor/git-essentials", "editor/pages", "editor/navigation", - "editor/keyboard-shortcuts", + "editor/live-preview", + "editor/branching-and-publishing", + "editor/agent", "editor/configurations", - "editor/settings" + "editor/settings", + "editor/keyboard-shortcuts" ] }, "create/text", diff --git a/editor/agent.mdx b/editor/agent.mdx new file mode 100644 index 0000000000..4541716042 --- /dev/null +++ b/editor/agent.mdx @@ -0,0 +1,90 @@ +--- +title: "Ask agent" +description: "Use the editor's built-in AI agent to write content, edit pages, search across your site, upload files, and configure settings from a chat interface." +keywords: ["editor", "AI", "assistant", "agent", "chat", "code mode", "file upload"] +--- + +The editor includes a built-in agent that can edit pages, reorganize navigation, update `docs.json`, search across your entire repository, and manage dashboard settings. + +The editor agent makes changes directly in your current branch. + +## Open the agent + +Click **Ask agent** in the editor toolbar, or press Cmd + I (macOS) or Ctrl + I (Windows). + +To close the panel, click the **X** button in the panel header or press Cmd + I again. + +## Send a message + +Type your request in the chat box at the bottom of the panel and press Enter or click the send button. + +Type @ to mention a specific page. The agent focuses on that page when processing your request. If you don't mention a page, the agent uses the page you currently have open. + +Example prompts: + +- `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"` + +## Attach files + +Click the paperclip icon in the chat box, or drag and drop files onto the panel. The agent reads attached files as context for your request. + +Supported file types: +- **Images**: JPG, PNG, GIF, WebP, SVG +- **Documents**: PDF +- **Code and text**: `.js`, `.ts`, `.jsx`, `.tsx`, `.mdx`, `.md`, `.json`, `.yaml`, `.html`, `.css`, Python, Go, Rust, Ruby, Java, Swift, C, C++, SQL, shell scripts, and more + +Maximum size: 5 MB per file. Maximum: 10 files per message. + +## Add a selection to the agent + +In visual mode, select text on a page. A floating toolbar appears over the selection. Click **Add to agent** to send the selected text to the agent as context. + +## Review what the agent changed + +As the agent edits your pages, a **Changed files** panel appears in the chat. Expand it to see a list of every file modified in the session. Click any file to open it in diff view and compare the agent's changes against the original. + +## What the agent can do + +### Edit pages + +The agent can write, rewrite, expand, and reorganize content on any page. It reads your existing content to match your style and structure. + +### Search and navigate your content + +The agent can search across your entire repository, not just the page you have open. Use it to find information, check for inconsistencies, or verify that content exists before adding it. + +### Update navigation and docs.json + +The agent can add, rename, reorder, and delete navigation elements, the same changes you'd make manually in the navigation panel. It can also update `docs.json` configuration directly, including adding new groups, adjusting settings, and configuring redirects. + +Example: `add a "Quickstart" group under the Getting Started tab and move the quickstart page into it` + +### Run bash commands + +The agent can run `grep`, `rg`, and other bash commands against your repository. Use this for bulk operations that span many files. + +Example: `find every page that mentions the deprecated /v1/auth endpoint` + +### Configure your site (code mode) + +For requests that go beyond editing pages (setting up authentication, managing workflows, or changing deployment settings), the agent switches into code mode. It writes and runs a script against your Mintlify dashboard on your behalf. + +Code mode respects your dashboard permissions. If you don't have access to a setting in the dashboard, the agent can't change it either. + +Example prompts that use code mode: + +- `enable JWT authentication for my site` +- `create a workflow that updates my site when I merge a PR` +- `add a custom domain` + +## Session history + +Click the clock icon in the panel header to see your previous chat sessions. Click any session to reopen it and see what the agent changed. + +## AI instructions + +To give the agent persistent guidance like voice rules, terminology, or formatting conventions, configure AI instructions in [Editor settings](/editor/settings#ai-instructions). The agent follows these instructions on every request without you needing to repeat them. diff --git a/editor/branching-and-publishing.mdx b/editor/branching-and-publishing.mdx index b215e225b6..20e24a9de0 100644 --- a/editor/branching-and-publishing.mdx +++ b/editor/branching-and-publishing.mdx @@ -28,7 +28,7 @@ The actions available when you click the publish button depend on your current b | Branch type | Branch protection | Available actions | |-------------|-------------------|-------------------| -| Deployment branch | None | **Publish** directly to your live site | +| Deployment branch | None | **Publish** directly to your live site | | Deployment branch | Pull requests required | **Create branch** to move changes to a new branch | | Feature branch | None | **Save in branch**, **Create pull request** | | Feature branch | Pull requests required | **Save in branch**, **Create pull request** | @@ -48,7 +48,7 @@ If there are no pending changes, the editor disables the publish and save action **Edit directly on your deployment branch** if you do not use a Git-based workflow. -**Create a branch** when you use a docs-as-code workflow where you make each change to your content on a separate branch. +**Create a branch** when you use a branch-based workflow where you make each change to your content on a separate branch. ## Create and switch branches @@ -79,7 +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. +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 @@ -129,12 +129,12 @@ For GitHub repositories, reviewers can approve open pull requests in the editor. 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. - Configure branch protection rules in your Git provider to require pull requests. See [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) in the GitHub docs or [Protected branches](https://docs.gitlab.com/user/project/repository/branches/protected/) in the GitLab docs. + Configure branch protection rules in your Git provider to require pull requests. See [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) in the GitHub help or [Protected branches](https://docs.gitlab.com/user/project/repository/branches/protected/) in the GitLab help. ### Review changes before merging -Click any changed file in the publish menu to open it in diff view and compare your branch against the published version. Files that can't display a diff, such as images or deleted files, appear in the list but aren't clickable. +Click any changed file in the publish menu to open it in diff view and compare your branch against the published version. In visual mode you see a visual diff; in source mode you see a text diff. Files that can't display a diff, such as images or deleted files, appear in the list but aren't clickable. ### Simultaneous publishing @@ -170,18 +170,5 @@ Non-overlapping changes apply automatically. If a remote change and your local e Sign commits with your GitHub account by authorizing it in your [account settings](https://app.mintlify.com/settings/account). Without authorization, the Mintlify GitHub App signs commits made in the web editor. -## Git operations reference - -For reference, here is how editor actions map to underlying Git operations. - -| Action in the editor | Git operation | -|---|---| -| Edit a page | Changes auto-save to Mintlify servers. No Git commit yet. | -| Publish on your deployment branch | `git commit` and `git push`. Triggers a deployment. | -| Save in branch | `git commit` to the current feature branch. | -| Create pull request | `git push` and opens a pull request against your deployment branch. | -| Merge and publish | Merges the pull request and triggers a deployment. | -| Create a branch | `git checkout -b ` | -| Switch branches | `git checkout ` | -| External push or CLI update | Incoming changes sync into the editor automatically using a three-way merge. | +For a reference of how editor actions map to Git operations, see [Git essentials](/editor/git-essentials#how-the-editor-maps-to-git). diff --git a/editor/collaborate.mdx b/editor/collaborate.mdx deleted file mode 100644 index 5d9c0c95e8..0000000000 --- a/editor/collaborate.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -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"] ---- - -Collaborate with your team on documentation using real-time editing and branch-based workflows. - -## Real-time collaboration - -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 - -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. - -- Each person's cursor and edits are visible to everyone on the page, with user avatars and names shown in the toolbar. -- Changes merge automatically. Two people editing the same section won't cause conflicts. -- 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. - -## 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. - -Use this to: - -- Watch agent changes stream into the page as they happen. -- See which paragraph or block the agent just updated without diffing the file. -- Coordinate with teammates and the agent on the same branch without overwriting each other's work. - -The agent's cursor clears automatically a short time after the agent finishes editing. - -## 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). - -### Why use branches - -- **Isolate changes**: Work on updates without affecting your live documentation. -- **Review before publishing**: Get feedback from team members before changes go live. -- **Parallel work**: Multiple team members can work on different branches simultaneously. - -## Recommended workflow - -Use pull requests to propose changes and collaborate with your team before merging to your live documentation. This workflow ensures your team reviews changes before publishing and maintains a clear history of updates. - - - - Create a pull request from the editor when you're ready to publish your changes. See [Branching and publishing](/editor/branching-and-publishing) for more information. - - - Review pull requests in your Git provider like GitHub or GitLab. - - - When reviewers request changes, make the requested changes in the editor. Additional changes automatically push to the existing pull request. - - - Merge your pull request after addressing all requested changes, required reviewers approve, and any automated checks pass. - - - -## 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. - -Anyone with access to your Mintlify organization can use the link to open the file directly in the editor. diff --git a/editor/configurations.mdx b/editor/configurations.mdx index 3e9ec1145d..10cb731c02 100644 --- a/editor/configurations.mdx +++ b/editor/configurations.mdx @@ -1,11 +1,11 @@ --- title: "Configurations" -description: "Edit site branding, colors, appearance, and feature settings from the Configurations panel in the Mintlify web editor, with real-time team sync." +description: "Edit site branding, appearance, navigation, and feature settings from the Configurations panel in the Mintlify web editor, with real-time team sync." keywords: ["editor", "configurations", "settings", "branding", "theme"] boost: 3 --- -Configure your documentation site's branding, appearance, and features from the **Configurations** panel in the web editor. Configuration changes sync in real-time with other editors on the same branch, so your team always sees the latest settings. +Configure your site's branding, appearance, and features from the **Site configurations** panel in the web editor. Configuration changes sync in real time with other editors on the same branch, so your team always sees the latest settings. -## Brand your site +The panel is organized into sections that map to the top-level properties in your [`docs.json`](/organize/settings). + +## General Set your site's identity and how it appears to visitors. -- **Docs title**: The name of your site. Appears in browser tabs and search results. -- **Description**: Brief summary of your documentation. Used for SEO and site metadata. -- **Favicon**: Small icon that appears in browser tabs. Upload ICO, PNG, GIF, or JPG files. +- **Name**: The name of your project. Appears in browser tabs and search results. +- **Description**: Brief overview of your project. Used for SEO and AEO. + +## Branding + +Upload the marks that identify your site. + +- **Logo**: Your brand logo. Upload PNG or JPG files. Set separate light and dark versions and an optional click-through URL. To use an SVG logo, add the file to your repository and reference its path in your [`docs.json`](/organize/settings-appearance#logos). +- **Favicon**: Small icon that appears in browser tabs. Upload ICO, PNG, GIF, or JPG files. Set separate light and dark versions if needed. -## Customize colors and appearance +## Styling Control your site's visual identity and color scheme. - **Theme**: Choose a [theme](/customize/themes) for your site's overall appearance. - **Primary color**: The main accent color used throughout your site for links, buttons, and highlights. -- **Light mode color**: Accent color variation for light mode. How themes apply this varies by theme. -- **Dark mode color**: Accent color variation for dark mode. How themes apply this varies by theme. -- **Logo**: Your brand logo. Upload PNG or JPG files. You can set different logos for light and dark modes. To use an SVG logo, add the file to your repository via Git and reference its path in your [docs.json](/organize/settings-appearance#logos) configuration. -- **Logo link**: Where users go when they click your logo. Typically your homepage or marketing site. -- **Background colors**: Set custom background colors for light and dark modes separately. -- **Background image**: Add a background image to your site. Upload PNG, GIF, or JPG files. -- **Background decoration**: Apply visual styles to your background image. -- **Theme toggle**: Show or hide the light/dark mode switcher for users. -- **Default theme**: Set whether your site loads in light or dark mode by default. - -## Set custom fonts +- **Light color**: Accent color used in dark mode. How themes apply this varies by theme. +- **Dark color**: Accent color used in light mode. How themes apply this varies by theme. +- **Background color**: Custom background colors for light and dark modes. +- **Icon library**: Icon library used for all icon properties. Defaults to `fontawesome`. +- **Strict appearance**: Lock the site to a single appearance mode and hide the theme toggle. +- **Default appearance**: Whether your site loads in `system`, `light`, or `dark` mode by default. +- **Background decoration**: Apply a visual style (`gradient`, `grid`, or `windows`) to your background. +- **Background image**: Optional background image. Set a single image or separate light and dark versions. -Replace default fonts with your brand's typography. +## Typography -- **Default font**: The base font family and weight for all text. Provide a source URL and format (WOFF or WOFF2). -- **Heading font**: Font family and weight specifically for headings (h1, h2, etc.). Set separately from body text. -- **Body font**: Font family and weight for body text and paragraphs. +Replace default fonts with your brand's typography. -For each font, specify the family name, weight, source URL (like Google Fonts), and format. +- **Font family**: Any [Google Fonts](https://fonts.google.com/) family works out of the box. For a self-hosted font, provide a source URL and format (`woff` or `woff2`). +- **Weight**: Typically `400` for regular and `700` for bold. Variable fonts support precise weights like `550`. +- **Heading font**: Optional override applied to all headings (`h1` through `h6`). +- **Body font**: Optional override applied to body text and the remainder of the page. -## Configure header and banner +## Navbar Add navigation elements to the top of your site. -- **Navbar links**: Add navigation links in your header. Each link includes text and a URL. -- **Banner**: Add a banner displayed at the top of every page. +- **Primary button**: The main call-to-action in your header. Set the type, label, and destination URL. +- **Navbar links**: Additional navigation links in your header. Each link includes text and a URL. -## Configure footer +## Footer Add links and social media handles to your site footer. -- **Social links**: Add your profiles on platforms like GitHub, X (Twitter), LinkedIn, Discord, YouTube, Slack, and more. -- **Footer columns**: Organize footer links into columns with custom headings and link groups. +- **Social links**: Profiles on platforms like GitHub, X, LinkedIn, Discord, YouTube, and Slack. +- **Footer columns**: Enable to organize footer links into up to four columns with custom headings. + +## Banner + +Display an announcement bar across the top of every page. -## Enhance content +- **Content**: The banner text. Supports basic MDX formatting like links, bold, and italic. Custom components are not supported. +- **dismissible**: Show a dismiss button on the right side of the banner. +- **Type**: Visual style. `info` uses the primary brand color, `warning` uses an amber background, and `critical` uses a red background. Defaults to `info`. +- **Color**: Override the banner background color with a custom hex color. Set separate light and dark values for theme-aware colors. + +## Thumbnail + +Customize page thumbnails and social previews. + +- **Background**: Custom background image for thumbnails. +- **Appearance**: Render thumbnails in `light` or `dark` mode. When unset, thumbnails are auto-generated from your theme colors. +- **Font**: Custom font for text in thumbnails. + +## Content Customize how content appears on your site. -- **Thumbnail background**: Set a custom background image for page thumbnails and social previews. -- **Thumbnail appearance**: Control how thumbnails display. -- **Thumbnail font**: Set a custom font for text in thumbnails. -- **Page eyebrow**: Add small labels preceding page titles. -- **Code block theme**: Choose the syntax highlighting theme for code blocks. -- **LaTeX support**: Enable mathematical notation rendering with LaTeX. -- **Icon library**: Choose the icon library to use for your site. +- **Page eyebrow**: Show small labels preceding page titles. Choose `section` or `breadcrumbs`. +- **Timestamps**: Show the date the content was last modified on all pages. +- **LaTeX**: Load LaTeX (KaTeX) stylesheets for mathematical notation rendering. -## Set up AI chat and search +## Codeblocks -Customize the search experience. +Configure syntax highlighting and code block behavior. -- **Search placeholder**: The text that appears in the search box before users type. Default is `Search or ask`. +- **Code block theme**: Match the site light/dark mode with `system`, always use a dark theme with `dark`, or pick a custom [Shiki](https://shiki.style/) theme. +- **Custom code languages**: Register additional syntax highlighting languages. + +## Context menu + +Configure the quick actions surfaced in the page context menu. + +- **Options**: Multi-select dropdown of actions like `copy`, `view`, and opening the page in `chatgpt`, `claude`, `cursor`, and other AI assistants. +- **Display**: Where to display the options. `header` (default) shows them in the top-of-page context menu; `toc` shows them in the table of contents sidebar. -## Connect integrations +## Navigation -Connect third-party tools for analytics, support, and compliance. +Tune navigation behavior across your site. -## API specifications +- **drilldown**: Auto-navigate to the first page when a user clicks a navigation group. + +## Search + +Customize the search experience and feedback. + +- **Search placeholder**: The text that appears in the search box before users type. Default is `Search or ask`. +- **Feedback**: Show thumbs-up and thumbs-down buttons or a "Suggest edits" link on every page. + +## API reference Document your API endpoints. -- **OpenAPI specs**: Upload an OpenAPI specification file to generate API reference pages. -- **AsyncAPI specs**: Upload an AsyncAPI specification file to generate API reference pages. -- **Playground display**: Choose to display the interactive API playground, simple API playground, or no API playground. +- **OpenAPI specs**: Add OpenAPI specification files to generate API reference pages. +- **AsyncAPI specs**: Add AsyncAPI specification files to generate API reference pages. +- **MDX server**: Custom MDX server endpoints for the API playground. +- **Playground display**: Show the interactive API playground, the simple API playground, or no API playground. - **Proxy server**: Enable or disable the proxy server for API requests. +- **`mdx.schema`**: Whether to render the schema section on API reference pages. -## Manage redirects +## Redirects -Use the **Redirects** section to add, edit, search, and remove redirects without manually editing your `docs.json` file. Redirects send users from old URLs to new ones, which is useful when you rename pages or restructure your documentation. For more information about redirect behavior, see [Redirects](/create/redirects). +Use the **Redirects** section to add, edit, search, and remove redirects without manually editing your `docs.json` file. Redirects send users from old URLs to new ones, which is useful when you rename pages or restructure your site. For more information, see [Redirects](/create/redirects). Each redirect has the following fields: - **Source**: The path to redirect from, like `/old-path`. Supports wildcards. -- **Destination**: The path to redirect to, like `/new-path`. +- **Destination**: The path to redirect to, like `/new-path`. Supports wildcards. - **Status**: The HTTP status code for the redirect. - `308`: Permanent redirect. Use this for content that has moved permanently. This is the default status. - `307`: Temporary redirect. Use this when the move is temporary. @@ -125,17 +163,34 @@ Each redirect has the following fields: To add a redirect: -1. Click **Add redirect** + +1. Click **Add redirect**. 2. Enter the source and destination. 3. Click **Save**. -To edit or remove an existing redirect: -1. Hover over the redirect. -2. Click the pencil icon to edit or the trash icon to remove. +To edit or remove an existing redirect, hover over the row and use the inline edit icon or the **X** to remove it. + +## SEO + +Configure metatags and indexing for search engines. + +- **metatags**: Custom `` tags applied across your site. Add key-value pairs for tags like `og:image` or `twitter:card`. +- **Indexing**: Choose whether to index hidden pages. + +## Analytics + +Connect analytics platforms to track visitor behavior. Supported providers include Amplitude, Mixpanel, Heap, Google Analytics, Google Tag Manager, PostHog, Plausible, Fathom, Segment, Hightouch, Hotjar, LogRocket, Microsoft Clarity, Intercom, Clearbit, and more. + +Each entry renders as an inline row. Use the **X** icon to remove an integration. + +## 404 page + +Customize the experience when a user lands on a missing page. + +- **Redirect to home**: When on, missing pages redirect to your home page. When off, a 404 page is shown and you can customize the title and description below. +- **Title**: Heading shown on the 404 page. +- **Description**: Subheading shown on the 404 page. -## Additional page behaviors +## Variables -- **404 pages**: Customize 404 pages and set up redirect behavior. -- **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. +Define custom variables that can be re-used throughout your content. Each variable is a key-value pair. Use the **X** icon to remove a variable. diff --git a/editor/git-essentials.mdx b/editor/git-essentials.mdx index 3133c1e02c..ea9a0ec69f 100644 --- a/editor/git-essentials.mdx +++ b/editor/git-essentials.mdx @@ -5,20 +5,20 @@ description: "Understand the Git version control concepts behind the Mintlify ed keywords: ["git", "version control", "web editor", "branches", "commits", "pull requests", "PRs"] --- -Git lets you control and track changes to files. Git is the version control system of choice for docs-as-code workflows, where you manage documentation the same way you would any other codebase. +Git lets you control and track changes to files. It's the version control system behind branch-based workflows, where you manage content the same way you would any other codebase. The web editor handles Git operations for you. Understanding a few key concepts helps you get the most out of the editor and collaborate effectively with your team. -## What Git does for your docs +## What Git does for your content -Git tracks every change made to your documentation. It records what changed, who changed it, when they changed it, and why. This means you can: +Git tracks every change made to your content. It records what changed, who changed it, when they changed it, and why. This means you can: - See the full history of any page. - Undo changes by reverting to a previous version. - Work on updates without affecting your live site. - Review changes before they go live. -Your documentation repository is the collection of files—and their history—that makes up your documentation site. The web editor connects to this repository to sync and publish your content. +Your repository is the collection of files and their history that makes up your site. The editor connects to this repository to sync and publish your content. ## Key concepts @@ -33,12 +33,12 @@ These are the Git concepts you'll encounter most often when using the web editor A separate line of work in your repository. Sometimes called a **feature branch**. - Your live documentation builds from a **deployment branch**, usually called `main`. Other branches let you work on changes independently without affecting your live site. Nothing on a branch goes live until you merge it into your deployment branch with a pull request. + Your live site builds from a **deployment branch**, usually called `main`. Other branches let you work on changes independently without affecting your live site. Nothing on a branch goes live until you merge it into your deployment branch with a pull request. Switch between branches using the branch dropdown in the editor toolbar. If you have unpublished changes, the editor lets you bring them to the new branch or leave them on your current branch. - The branch that builds your live documentation site, typically called `main`. Changes merged into this branch automatically deploy to your site. + The branch that builds your live site, typically called `main`. Changes merged into this branch automatically deploy to your site. A proposal to merge changes from one branch into another. Pull requests let your team review and discuss changes before they go live. @@ -58,12 +58,15 @@ These are the Git concepts you'll encounter most often when using the web editor ## How the editor maps to Git -Every publish action in the web editor corresponds to a Git operation. +Every action in the web editor corresponds to a Git operation. Here is the full reference: -| Your action in the editor | Git operation behind the scenes | +| Action in the editor | Git operation | |---|---| -| Edit a page | Changes auto-save to Mintlify servers (no Git commit yet) | -| Switch branches | Check out the selected branch | -| Publish on your deployment branch | Commit changes to your repository and trigger a deployment | -| Publish on a feature branch | Commit changes and create a pull request | -| External push or CLI update | Incoming changes sync into the editor automatically | +| Edit a page | Changes auto-save to Mintlify servers. No Git commit yet. | +| Publish on your deployment branch | `git commit` and `git push`. Triggers a deployment. | +| Save in branch | `git commit` to the current feature branch. | +| Create pull request | `git push` and opens a pull request against your deployment branch. | +| Merge and publish | Merges the pull request and triggers a deployment. | +| Create a branch | `git checkout -b ` | +| Switch branches | `git checkout ` | +| External push or CLI update | Incoming changes sync into the editor automatically using a three-way merge. | diff --git a/editor/index.mdx b/editor/index.mdx index 7f4b846acf..dc23b6d443 100644 --- a/editor/index.mdx +++ b/editor/index.mdx @@ -1,27 +1,17 @@ --- title: "Editor overview" sidebarTitle: "Overview" -description: "Create, edit, and publish documentation in your browser with real-time team collaboration, automatic saving, live previews, and continuous Git sync." +description: "Create, edit, and publish content in your browser with real-time team collaboration, automatic saving, live previews, and continuous Git sync." keywords: ["editor", "visual", "collaborative", "web editor"] --- -Decorative image of the web editor in light mode - -Decorative image of the web editor in dark mode - -The editor keeps your content in sync with your Git repository and lets your whole team edit together in real time. + + A step-by-step walkthrough: create a branch, make a change, share a preview, and publish. + ## How the editor works -**Changes save automatically.** As you type, the editor saves changes. Your work persists across tabs, devices, and network interruptions. +**Changes save automatically.** As you type, the editor saves your draft. Your work persists across tabs, devices, and network interruptions. Changes only go live when you publish them. **Git stays in sync.** When someone else pushes changes to your repository from outside the editor, those changes appear in the editor automatically. You don't need to pull or refresh. The editor merges non-conflicting changes and highlights anything that needs your attention. @@ -29,14 +19,28 @@ The editor keeps your content in sync with your Git repository and lets your who **Your team edits together.** Multiple people can edit the same page simultaneously. Live cursors show who is editing and where. +## The editor layout + + + Screenshot of the editor showing the branch selector, ask agent button, publish button, navigation sidebar, and top bar. + Screenshot of the editor showing the branch selector, ask agent button, publish button, navigation sidebar, and top bar. + + +- **Top bar**: Use the top bar to control what branch you work on, access the agent, preview, and publish changes. +- **Navigation sidebar**: Select a page to edit, create new pages, and manage the site structure. + ## Explore the editor How branches and protection rules determine what happens when you publish, and how to manage the pull request review process. + + Edit pages, search your content, modify settings, and configure your site from a chat interface. + + - Everything you need to add new and update existing pages. + Add new and update existing pages. @@ -48,5 +52,5 @@ The editor keeps your content in sync with your Git repository and lets your who - Speed up your workflow with keyboard shortcuts. + Save time with keyboard shortcuts. diff --git a/editor/keyboard-shortcuts.mdx b/editor/keyboard-shortcuts.mdx index 9014630ab0..b58cc9788f 100644 --- a/editor/keyboard-shortcuts.mdx +++ b/editor/keyboard-shortcuts.mdx @@ -6,15 +6,22 @@ keywords: ["editor", "keys", "keyboard", "shortcuts"] Use keyboard shortcuts to navigate and edit faster in the web editor. The editor supports common shortcuts like copy, paste, undo, and select all, along with the shortcuts listed below. -## Visual mode - -Use these shortcuts when editing in visual mode. +## Editor-wide -### Search and navigation +These shortcuts work regardless of which mode you're in. | Command | macOS | Windows | | :--- | :--- | :--- | | **Search files and content** | Cmd + K | Ctrl + K | +| **Toggle AI assistant** (when not editing text) | Cmd + I | Ctrl + I | +| **Switch between visual and source mode** | Cmd + Shift + M | Ctrl + Shift + M | +| **Toggle diff view** | Cmd + Shift + D | Ctrl + Shift + D | +| **Switch between Navigation and Files tree** | Cmd + Shift + F | Ctrl + Shift + F | +| **Hide/show sidebar** | Cmd + \\ | Ctrl + \\ | + +## Visual mode + +Use these shortcuts when editing in visual mode. ### Text formatting @@ -67,9 +74,9 @@ The editor automatically converts certain character sequences into typographic s | `>=` | ≥ | | `!=` | ≠ | -## Markdown mode +## Source mode -Markdown mode uses the Monaco editor, which supports standard VS Code keyboard shortcuts. +Source mode uses the Monaco editor, which supports standard VS Code keyboard shortcuts. ### Search and navigation diff --git a/editor/live-preview.mdx b/editor/live-preview.mdx index 881153291b..c759c07cee 100644 --- a/editor/live-preview.mdx +++ b/editor/live-preview.mdx @@ -1,6 +1,6 @@ --- title: "Live preview" -description: "Preview your documentation site in real time as you edit, with continuous updates that render content, navigation, and configuration changes instantly." +description: "Preview your site in real time as you edit, with continuous updates that render content, navigation, and configuration changes instantly." keywords: ["editor", "preview", "live preview"] --- @@ -8,7 +8,7 @@ Preview your site while you edit. Live previews render pages exactly as they loo ## 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 top bar to open a live preview in a new tab. live preview button in the toolbar to open a live - Live preview is only available for public documentation. + Live preview is only available for public sites. ## Live preview versus preview deployments diff --git a/editor/pages.mdx b/editor/pages.mdx index ed3df9e41d..3a0ae1943d 100644 --- a/editor/pages.mdx +++ b/editor/pages.mdx @@ -1,31 +1,46 @@ --- title: "Create and edit pages" -description: "Create pages, edit content, upload images and video, and manage files in the Mintlify web editor with rich-text editing and search across your docs." +description: "Create pages, edit content, upload images and video, and manage files in the Mintlify web editor with rich-text editing and search across your content." keywords: ["editor", "content", "pages", "files", "create", "edit", "media", "images", "video"] --- ## 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**. - - 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. - +**Navigation** shows your sidebar structure as visitors see it. 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. + +To switch between views, click the file icon or press Cmd + Shift + F (macOS) or Ctrl + Shift + F (Windows). Click the search icon or press Cmd + K (macOS) or Ctrl + K (Windows) to search by filename or page content. + +## Manage files and folders + +Use the Files view 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 file in the tree to open it, even if it isn't included in your navigation. + +Files that aren't in your navigation are unlisted. They exist in your repository but won't appear in the published 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. -## Edit content +### Create an unlisted page -Switch between visual and Markdown mode with the toggle in the toolbar. +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. - - The mode toggle in the editor toolbar. - The mode toggle in the editor toolbar. - +Right-click any folder in the Files view 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 source mode using the mode toggle in the toolbar below the top bar. Click the eye icon or press Cmd + Shift + M (macOS) or Ctrl + Shift + M (Windows) to switch to visual mode. Click the code icon or press Cmd + Shift + M (macOS) or Ctrl + Shift + M (Windows) to switch to source mode. **Visual mode** shows a real-time preview as you type. Press / to open the component menu and insert components, images, videos, and other content. You can also drag and drop media files directly onto the page from your computer or from the navigation tree. Other shortcuts: @@ -35,19 +50,21 @@ Switch between visual and Markdown mode with the toggle in the toolbar. - **Insert an emoji**: Type : followed by a keyword to open the emoji picker. - **Edit a table**: When your cursor is inside a table, use the floating toolbar to add or remove rows and columns, or merge cells. -**Markdown mode** gives you direct access to the MDX source. Use it for precise control over component properties and frontmatter. - - - The web editor treats API specification files (OpenAPI and AsyncAPI) as read-only. Edit them in your code editor and push the changes to your repository. - +**Source mode** gives you direct access to the MDX source. Use it for precise control over component properties and frontmatter. For a full list of components, see [Components](/components). For MDX syntax, see [Format text](/create/text) and [Format code](/create/code). +### Diff view + +To compare your current page against the last published version, click the **View diff** button in the toolbar, or press Cmd + Shift + D (macOS) or Ctrl + Shift + D (Windows). In visual mode this shows a visual diff. In source mode it shows a text diff. Click **Exit diff** or press the shortcut again to return to editing. + +You can also open a diff from the publish menu. Click **Publish** then click any changed file in the list. + ### Block actions In visual mode, hover over any block to reveal a drag handle on the left. Click the handle to open a context menu with actions for that block: -- **Turn into**: Convert the block to a different type—text, headings, blockquote, or list. +- **Turn into**: Convert the block to a different type: text, headings, blockquote, or list. - **Duplicate**: Insert a copy of the block immediately after it. - **Delete**: Remove the block. @@ -71,9 +88,9 @@ When editing a code block in visual mode, you can: ## Review changes before publishing -Open the publish menu and click any changed file to enter diff view. The editor highlights differences between your draft and the last published version. If you're in visual mode, you see a visual diff. If you're in Markdown mode, you see a Markdown diff. +Open the publish menu and click any changed file to enter diff view. The editor highlights differences between your draft and the last published version. In visual mode you see a visual diff; in source mode you see a text diff. -Diff view is read-only. Click the button next to the mode toggle to return to editing. +Click **Exit diff** or press Cmd + Shift + D (macOS) or Ctrl + Shift + D (Windows) to return to editing. ## Manage pages @@ -102,7 +119,7 @@ For details on each setting, see [Pages](/organize/pages). Type /image to upload a new image or select an existing one from your repository. Type /video to upload or select a video. -You can also drag and drop files from your computer directly onto a page. In visual mode, the file inserts inline. In Markdown mode, the editor inserts the file path at your cursor position. Images save to your `images/` folder and videos to `videos/`. +You can also drag and drop files from your computer directly onto a page. In visual mode, the file inserts inline. In source mode, the editor inserts the file path at your cursor position. Images save to your `images/` folder and videos to `videos/`. To reuse media that already lives in your project, drag an image or video file from the navigation tree onto the page. The editor embeds the asset inline. diff --git a/editor/settings.mdx b/editor/settings.mdx index e80bec8d38..94a3547c48 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. ## 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. Click the settings icon in the editor 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 deleted file mode 100644 index 0060a2a8a3..0000000000 --- a/editor/share-a-preview.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Share a preview" -description: "Share preview deployment URLs and editor links from your feature branch to gather feedback and review documentation changes before publishing them live." -keywords: ["editor", "preview", "preview deployment", "share", "collaboration", "feedback"] ---- - -## 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. - -### 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`. - -### Share your preview - -Copy the preview 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 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. - -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` - diff --git a/editor/tutorial.mdx b/editor/tutorial.mdx index 329e9c3120..b1fbab9a6b 100644 --- a/editor/tutorial.mdx +++ b/editor/tutorial.mdx @@ -1,6 +1,6 @@ --- title: "How to use the editor" -description: "Step-by-step walkthrough of the Mintlify editor: create a branch, edit pages, share a preview deployment for review, and publish your documentation changes." +description: "Step-by-step walkthrough of the Mintlify editor: create a branch, edit pages, share a preview deployment for review, and publish your changes." keywords: ["editor", "tutorial", "branch", "publish"] --- @@ -23,12 +23,12 @@ This tutorial walks you through a complete content update using the editor. You' 1. Enter a name that describes your change, like `update-quickstart`. 1. Click **Create branch**. - The editor switches to your new branch. Any changes you make are only on the branch. They only appear on your live site when you complete the publishing process. + The editor switches to your new branch. Any changes you make are only on the branch. They only appear on your live site if you complete the publishing process. Edit an existing page or create a new one. - **To edit a page**: Click it in the navigation sidebar to open it. Type directly in the editor to add content. Press / to insert components, images, or other content. + **To edit a page**: Click the page name in the navigation sidebar to open it. Type directly in the editor to add content. Press / to insert components, images, or other content. **To create a page**: Click the plus button next to the navigation group where you want to add the page, then click **Add a page** and enter a filename. @@ -39,25 +39,29 @@ This tutorial walks you through a complete content update using the editor. You' - To review your changes, you must create a pull request. A pull request is a proposal to merge your changes into the main branch that builds your site. + When you're ready for review, publish your branch to create a pull request. A pull request is a proposal to merge your changes into the branch that builds your live site. Your changes only go live if the pull request is approved and merged. - When you publish your branch, you make it available for review by your team. The changes only appear on your live site if you merge the pull request. - - 1. Click **Publish** in the toolbar to open the publish menu. + 1. Click **Publish** in the toolbar to open the publish menu. The publish menu opened in the editor toolbar. The publish menu opened in the editor toolbar. 1. Optionally, click any changed file in the list to view and compare your edits against the published version. - 1. Click **Save in branch** to save all changes on your branch. + 1. Click **Save in branch** to commit your changes to the branch. 1. Click **Create pull request**. Add a title and description, then click **Publish pull request**. - 1. Continue to GitHub to view your pull request and review your changes. + After the pull request is created, a preview deployment builds automatically. The publish menu shows the preview URL, a temporary link where your changes render exactly as they would on your live site. Share this URL with your reviewers. - - Share your pull request with your team to review your changes. + + Share the pull request with your team. Reviewers can open the pull request in GitHub or GitLab to leave comments, request changes, or approve it. + + If a reviewer requests changes, make the edits in the editor on the same branch. Your updates push to the existing pull request automatically. You don't need to create a new one. + + When all required reviewers have approved, the pull request is ready to merge. - - After your team approves your changes, merge your pull request into the main branch. Your changes deploy to your live site. + + With the pull request approved, click **Publish** in the toolbar to reopen the publish menu. The menu now shows the pull request status and an option to merge. + + Click **Merge and publish**. The editor merges the pull request and switches you back to your deployment branch. Mintlify builds and deploys your changes. Your live site updates in about 30 seconds to a few minutes. diff --git a/images/editor/configurations-dark.png b/images/editor/configurations-dark.png index d889295e50..ca32529795 100644 Binary files a/images/editor/configurations-dark.png and b/images/editor/configurations-dark.png differ diff --git a/images/editor/configurations-light.png b/images/editor/configurations-light.png index 6406aa9e84..db480fbc18 100644 Binary files a/images/editor/configurations-light.png and b/images/editor/configurations-light.png differ diff --git a/images/editor/create-branch-dark.png b/images/editor/create-branch-dark.png index 8a304a1987..3ddf10c003 100644 Binary files a/images/editor/create-branch-dark.png and b/images/editor/create-branch-dark.png differ diff --git a/images/editor/create-branch-light.png b/images/editor/create-branch-light.png index 49d032e8ad..9989e2fad3 100644 Binary files a/images/editor/create-branch-light.png and b/images/editor/create-branch-light.png differ diff --git a/images/editor/editor-layout-dark.png b/images/editor/editor-layout-dark.png new file mode 100644 index 0000000000..101c433099 Binary files /dev/null and b/images/editor/editor-layout-dark.png differ diff --git a/images/editor/editor-layout-light.png b/images/editor/editor-layout-light.png new file mode 100644 index 0000000000..a13dd4373a Binary files /dev/null and b/images/editor/editor-layout-light.png differ