diff --git a/create/reusable-snippets.mdx b/create/reusable-snippets.mdx index 49d87c6ad..42422d90b 100644 --- a/create/reusable-snippets.mdx +++ b/create/reusable-snippets.mdx @@ -6,6 +6,10 @@ keywords: ["content snippets", "reusable content", "variables"] One of the core principles of software development is DRY (Don't Repeat Yourself), which applies to documentation too. If you find yourself repeating the same content in multiple places, create a custom snippet for that content. Snippets contain content that you can import into other files to reuse. You control where the snippet appears on a page. If you ever need to update the content, you only need to edit the snippet rather than every file where the snippet is used. + + Snippets are not currently supported in the web editor. To use snippets, edit your MDX files locally with the CLI or push snippet imports directly to your repository. + + ## How snippets work Snippets are any `.mdx`, `.md`, or `.jsx` files imported into another file. You can place snippet files anywhere in your project. diff --git a/docs.json b/docs.json index f534dd729..210b020ad 100644 --- a/docs.json +++ b/docs.json @@ -81,20 +81,20 @@ "icon": "pen-line", "pages": [ { - "group": "Web editor", + "group": "Editor", + "tag": "New", "root": "editor/index", "pages": [ - "editor/git-essentials", + "editor/tutorial", + "editor/branching-and-publishing", + "editor/live-preview", "editor/pages", - "editor/media", "editor/navigation", - "editor/configurations", - "editor/live-preview", - "editor/collaborate", - "editor/publish", - "editor/keyboard-shortcuts" + "editor/keyboard-shortcuts", + "editor/configurations" ] }, + "editor-classic", "create/text", "create/code", { diff --git a/editor-classic.mdx b/editor-classic.mdx new file mode 100644 index 000000000..eb7178794 --- /dev/null +++ b/editor-classic.mdx @@ -0,0 +1,41 @@ +--- +title: "Web editor" +description: "The classic Mintlify web editor for creating and publishing documentation in your browser. Sunsetting May 7, 2026." +keywords: ["editor", "visual editor", "web editor"] +tag: "Classic" +--- + + + The classic web editor fully deprecates on May 7, 2026. + + The new editor is now available with real-time collaboration, automatic saving across devices, and improved syncing. See [Editor](/editor) for more information. + + +The web editor lets you create, edit, and publish documentation directly in your browser. + +## Editor modes + +The editor has two modes you can switch between using the toggle in the toolbar. + +**Visual mode** shows a live preview of your content as you type. Press / to insert components and media, or format text. + +**Markdown mode** gives you direct access to the MDX source of your pages. Use this for precise control over component properties and frontmatter. + +## Publish changes + +The branch you work on determines how the editor publishes your changes. If you have branch protection rules on your repository, the editor enforces them. + +- **Deployment branch**: Publishing updates your live site immediately. +- **Feature branches**: Publishing creates a pull request for review before deploying to your live site. + +## Keyboard shortcuts + +| Command | macOS | Windows | +| :--- | :--- | :--- | +| **Search files** | Cmd + K | Ctrl + K | +| **Bold** | Cmd + B | Ctrl + B | +| **Italic** | Cmd + I | Ctrl + I | +| **Underline** | Cmd + U | Ctrl + U | +| **Code** | Cmd + E | Ctrl + E | +| **Add link** | Cmd + K | Ctrl + K | +| **Component menu** | / | / | diff --git a/editor/branching-and-publishing.mdx b/editor/branching-and-publishing.mdx new file mode 100644 index 000000000..3fa407488 --- /dev/null +++ b/editor/branching-and-publishing.mdx @@ -0,0 +1,175 @@ +--- +title: "Branching and publishing" +description: "Understand how branches and protection rules determine what happens when you publish, and how to manage the full review and deployment workflow." +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**. + +## Saving versus publishing + +**Saving** happens automatically. Your edits are stored on Mintlify's servers and persist across browser tabs, devices, and network interruptions. + +**Publishing** commits your changes to your Git repository. Click the **Publish** button in the toolbar to open the publish menu, save your changes as a Git commit, and create a pull request. + +The editor tracks the following as pending changes: + +- Content edits in pages +- New or deleted pages +- Navigation structure changes +- Media uploads +- Configuration updates + +## What happens when you publish + +The actions available when you click the publish button depend on your current branch and whether it has branch protection rules that require pull requests. + +| Branch type | Branch protection | Available actions | +|-------------|-------------------|-------------------| +| 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** | + +- **Publish**: Commits and deploys your changes to your live site immediately. +- **Save in branch**: Commits your changes to the feature branch without merging to your deployment branch. +- **Create branch**: Moves your pending changes to a new feature branch when you're on a protected deployment branch. +- **Create pull request**: Opens a pull request targeting your deployment branch. + +If there are no pending changes, the publish and save actions are disabled. + + + Your live site updates after Mintlify builds and deploys your changes. This typically takes 30 seconds to a few minutes. Check the deployment status on your [dashboard](https://dashboard.mintlify.com). + + +## When to use a branch + +**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 each change to your content is made on a separate branch. + +## Create and switch branches + +### Create a branch + +1. Click the branch name in the editor toolbar. +1. Click **Create new branch**. +1. If you have pending changes, choose whether to bring them to the new branch or leave them on the current branch. +1. Enter a name and click **Create branch**. + + + Use descriptive branch names so you can easily identify them and other people understand what each branch is for. + + +### Switch branches + +1. Click the branch name in the toolbar. +1. Search for or scroll to the branch you want. +1. Click the branch to switch to it. + + + Switching branches while you have unpublished changes will prompt you to bring those changes to the new branch or leave them behind. Changes left behind remain on your original branch. + + +## 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://dashboard.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://dashboard.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath} +``` + +For example: `https://dashboard.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx` + +## Review and merge pull requests + +When a pull request is open for the current branch, the publish menu shows its review status: + +- **Approved**: The pull request has been approved and is ready to merge. +- **Changes requested**: A reviewer has requested changes before the pull request can merge. +- **Awaiting review**: The pull request is waiting for a reviewer. + +Click **View request** to open the pull request in your Git provider. + +When the pull request is approved, click **Merge and publish** to merge and deploy directly from the editor. The editor switches to your deployment branch after merging. + + + 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. + + +### 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. + +### Simultaneous publishing + +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. + +### 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. + +## 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. + +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 + +When someone pushes changes to your repository from outside the editor, the editor incorporates those changes automatically. + +Non-overlapping changes apply automatically. If a remote change and your local edit affect the same part of a page, the editor highlights the conflict so you can resolve it. + +## Commit signing + +Sign commits with your GitHub account by authorizing it in your [account settings](https://dashboard.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. | + diff --git a/editor/collaborate.mdx b/editor/collaborate.mdx index 1726f8494..f6d8ad36b 100644 --- a/editor/collaborate.mdx +++ b/editor/collaborate.mdx @@ -1,17 +1,47 @@ --- title: "Collaborate in the web editor" sidebarTitle: "Collaborate" -description: "Collaborate on documentation in the web editor with branches, pull requests, preview deployments, shareable links, and real-time editing." -keywords: ["editor", "collaboration", "branches", "pull requests", "preview deployments", "share links"] +description: "Edit documentation simultaneously with your team using real-time collaboration, live cursors, and branch-based workflows." +keywords: ["editor", "collaboration", "real-time", "live editing", "branches", "pull requests", "preview deployments", "share links"] --- -Collaborate with your team on documentation using branch-based workflows, pull requests, and preview deployments. +Collaborate with your team on documentation using real-time editing and branch-based workflows. -If you aren't familiar with Git, see [Git essentials for the web editor](/editor/git-essentials). +## 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. +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 @@ -25,16 +55,16 @@ Use pull requests to propose changes and collaborate with your team before mergi - Create a pull request from the editor when you're ready to publish your changes. See Publish changes in the web editor for more information on using pull requests. + 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 and save your changes. Additional changes automatically push to the existing pull request. + 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 the pull request, and any automated checks pass. + Merge your pull request after addressing all requested changes, required reviewers approve, and any automated checks pass. @@ -42,21 +72,16 @@ Use pull requests to propose changes and collaborate with your team before mergi 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 save changes to a branch, the preview deployment updates automatically. +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 button in the editor toolbar - Share button in the editor toolbar - - ### Share previews -Share the preview deployment URL with team members to gather feedback. Previews update automatically when you save additional changes. +Share the preview deployment URL with team members to gather feedback. Previews update automatically when you publish additional changes. ### Preview authentication @@ -64,16 +89,12 @@ Preview URLs are publicly accessible by default. Enable preview authentication i ## Share editor links -Share a direct link to a specific page in the editor with your teammates. Use editor links to collaborate on updates and make changes to pages. +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. -When you open a page, the editor saves the path in the URL. Copy the URL from your browser's address bar to share it with teammates who have access to the editor. +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://dashboard.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}` For example, `https://dashboard.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. - - - When you share a page, tell people which branch you're working on so they can confirm they view the correct version. - diff --git a/editor/configurations.mdx b/editor/configurations.mdx index 3dec6e1df..cdbcbcc44 100644 --- a/editor/configurations.mdx +++ b/editor/configurations.mdx @@ -1,20 +1,20 @@ --- title: "Configurations" -description: "Edit page metadata, navigation elements, and media settings using the visual configuration sheets in the Mintlify web editor sidebar." -keywords: ["editor", "configurations", "settings"] +description: "Edit site branding, appearance, and feature settings using the visual configuration sheet in the Mintlify web editor." +keywords: ["editor", "configurations", "settings", "branding", "theme"] --- -Configure your documentation site's branding, appearance, and features from the **Configurations** panel in the web editor. +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. Configurations settings in the sidebar in light mode. Configurations settings in the sidebar in dark mode. @@ -23,15 +23,15 @@ Configure your documentation site's branding, appearance, and features from the Set your site's identity and how it appears to visitors. -- **Docs title**: The name of your documentation. Appears in browser tabs and search results. +- **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. -- **Theme**: Choose a [theme](/customize/themes) for your documentation's overall appearance. ## Customize colors and appearance 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. @@ -53,12 +53,12 @@ Replace default fonts with your brand's typography. For each font, specify the family name, weight, source URL (like Google Fonts), and format. -## Configure header +## Configure header and banner Add navigation elements to the top of your site. -- **Navbar button**: Add a primary call-to-action button in your header. Set the button type, label, and destination URL. -- **Navbar links**: Add additional navigation links in your header. Each link includes text and a URL. +- **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. ## Configure footer @@ -77,6 +77,7 @@ Customize how content appears on your site. - **Page eyebrow**: Add small labels above 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. ## Set up AI chat and search @@ -84,29 +85,22 @@ Customize the search experience. - **Search placeholder**: The text that appears in the search box before users type. Default is "Search or ask...". -## Configure API specifications +## Connect integrations -Add [OpenAPI](/api-playground/openapi-setup) or [AsyncAPI](/api-playground/asyncapi-setup) specification files to document endpoints. +Connect third-party tools for analytics, support, and compliance. -- **OpenAPI specs**: Upload an OpenAPI specification file or enter a URL to an external OpenAPI file. -- **AsyncAPI specs**: Upload an AsyncAPI specification file or enter a URL to an external AsyncAPI file. -- **Playground display**: Choose to display the interactive API playground, simple API playground, or no API playground. -- **Proxy server**: Enable or disable the proxy server for API requests. +## API specifications -## Add analytics and integrations +Document your API endpoints. -Connect analytics and third-party tools to your documentation. +- **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. +- **Proxy server**: Enable or disable the proxy server for API requests. -Track visitor behavior with: -- **Amplitude, Mixpanel, Heap**: Product analytics platforms -- **Google Analytics, Google Tag Manager**: Web analytics -- **PostHog, Plausible, Fathom**: Privacy-focused analytics -- **Segment, Hightouch**: Customer data platforms -- **Hotjar, LogRocket**: Session replay and heatmaps -- **Microsoft Clarity**: User behavior analytics -- **Intercom**: Customer messaging -- **Clearbit, Koala**: Visitor identification +## Additional page behaviors -Additional integrations: -- **Telemetry**: Enable or disable usage telemetry -- **Cookies**: Set custom cookie key and value pairs +- **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. diff --git a/editor/git-essentials.mdx b/editor/git-essentials.mdx index d5809f5dd..d11bc9310 100644 --- a/editor/git-essentials.mdx +++ b/editor/git-essentials.mdx @@ -1,13 +1,13 @@ --- -title: "Git essentials for the web editor" +title: "Git essentials for the editor" sidebarTitle: "Git essentials" -description: "Understand the Git version control concepts behind the Mintlify web editor, including branches, commits, pull requests, and merge workflows." +description: "Understand the Git version control concepts behind the Mintlify editor, including branches, commits, pull requests, and merge workflows." 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. 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. -The web editor handles Git operations for you. Understanding a few key concepts helps you get the most out of the editor and collaborate with your team. +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 @@ -18,7 +18,7 @@ Git tracks every change made to your documentation. It records what changed, who - 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 make up your documentation site. The web editor connects to this repository to read and update your content. +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. ## Key concepts @@ -28,14 +28,14 @@ These are the Git concepts you'll encounter most often when using the web editor A saved snapshot of your changes at a specific point in time. Each commit includes a message describing what changed and creates a permanent record in your project history. - When you save changes, the web editor creates a commit. + When you publish changes, the web editor creates a commit in your Git repository. 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. Nothing on a branch affects your live site until you merge it into your deployment branch with a pull request. - When you create a branch, the web editor creates a new branch in your repository. You can search for and switch between branches from the branch dropdown in the toolbar. If you have unsaved changes, the editor lets you bring them to the new branch or leave them on your current 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. + + 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. @@ -43,27 +43,27 @@ These are the Git concepts you'll encounter most often when using the web editor A proposal to merge changes from one branch into another. Pull requests let your team review and discuss changes before they go live. - When you publish changes on a feature branch, the web editor creates a pull request. Your team reviews and merges the pull request in your Git provider (GitHub or GitLab). + When you publish changes on a feature branch (or when your repository requires pull requests), the web editor creates a pull request. Your team reviews and merges the pull request in your Git provider (GitHub or GitLab). Combining changes from one branch into another. After your team reviews and approves a pull request, merging the branch incorporates your changes into the deployment branch and publishes them. - Occurs when two people change the same part of a file differently. The editor helps resolve any conflicts that occur on your branches. + Occurs when two branches have incompatible changes to the same files. The editor helps you resolve conflicts when they occur. - A comparison showing the differences between two versions of a file. When reviewing pull requests, diffs highlight exactly what changed. The web editor can show diffs for individual files when you review branch changes before publishing. + A comparison showing the differences between two versions of a file. The editor shows a visual diff of your pending changes before you publish so you can review exactly what will be committed. ## How the editor maps to Git -Every action you take in the web editor corresponds to a Git operation. +Every publish action in the web editor corresponds to a Git operation. | Your action in the editor | Git operation behind the scenes | |---|---| -| Open a file | Fetch the latest version from your repository | -| Save changes | Create a **commit**, a snapshot of your changes in the project history | -| Create a branch | Create a **branch**, a separate line of work that doesn't affect your live site unless you choose to publish it | -| Publish on your deployment branch | Push your commit directly, which triggers a deployment | -| Publish on a feature branch | Create a **pull request**, a proposal to merge your changes into the deployment branch | +| 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 | diff --git a/editor/index.mdx b/editor/index.mdx index 9e6251fd9..1c367a9ba 100644 --- a/editor/index.mdx +++ b/editor/index.mdx @@ -1,65 +1,50 @@ --- -title: "Web editor overview" +title: "Editor overview" sidebarTitle: "Overview" -description: "Create, edit, and publish documentation directly in your browser with visual editing, live preview, Git sync, and team collaboration tools." -keywords: ["editor", "visual", "gitbook"] +description: "Create, edit, and publish content directly in your browser with real-time collaboration, automatic saving, and Git sync." +keywords: ["editor", "visual", "collaborative", "web editor"] --- Decorative image in light mode Decorative image in dark mode -Create, edit, and publish documentation directly in your browser with the web editor. View and share previews of your changes, manage your site's navigation structure with drag-and-drop components, and publish updates using your team's preferred workflow. +The editor keeps your content in sync with your Git repository and lets your whole team edit together in real time. -## Key features +## How the editor works -- **Visual and Markdown editing**: Switch between visual and Markdown editing modes to suit your workflow. -- **Live preview**: See real-time changes without creating a preview deployment. -- **Shareable preview links**: Create preview links for your team from the editor. -- **Drag-and-drop navigation**: Organize your site structure visually without editing configuration files. -- **Git synchronization**: All changes sync automatically with your documentation repository. -- **Team collaboration**: Multiple team members can work simultaneously with branch-based workflows. +**Changes save automatically.** As you type, the editor saves changes. Your work persists across tabs, devices, and network interruptions. -## Get started +**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. - - Create, edit, and organize pages. - +**Publishing writes to Git.** When you publish, the editor commits your changes to your repository. On a deployment branch, this updates your live site immediately. On a feature branch, it creates a pull request. - - Structure your site navigation. - +**Your team edits together.** Multiple people can edit the same page simultaneously. Live cursors show who is editing and where. - - Upload and use images, videos, and other assets. - +## Explore the editor - - Preview your site in real time as you edit. + + How branches and protection rules determine what happens when you publish, and how to manage the pull request review process. -## Publish and collaborate - - - Save and publish your documentation updates. + + Everything you need to add new and update existing pages. - - Work with teams using branches and pull requests. + + Reorder pages and manage site structure. -## Reference - - Configure site branding, colors, and features. + Configure your site's branding, colors, and features. diff --git a/editor/keyboard-shortcuts.mdx b/editor/keyboard-shortcuts.mdx index a39b770dc..9014630ab 100644 --- a/editor/keyboard-shortcuts.mdx +++ b/editor/keyboard-shortcuts.mdx @@ -1,6 +1,6 @@ --- title: "Keyboard shortcuts" -description: "View the complete list of keyboard shortcuts for the Mintlify web editor, including text formatting, navigation, and editing key commands." +description: "View the complete list of keyboard shortcuts for the Mintlify web editor, including text formatting, navigation, and editing commands." keywords: ["editor", "keys", "keyboard", "shortcuts"] --- @@ -8,7 +8,7 @@ Use keyboard shortcuts to navigate and edit faster in the web editor. The editor ## Visual mode -Use these shortcuts when editing in Visual mode. +Use these shortcuts when editing in visual mode. ### Search and navigation diff --git a/editor/live-preview.mdx b/editor/live-preview.mdx index bd4e55d01..d97bb0f28 100644 --- a/editor/live-preview.mdx +++ b/editor/live-preview.mdx @@ -1,39 +1,39 @@ --- title: "Live preview" -description: "Preview your documentation site in real time as you edit with the web editor's side-by-side live preview and responsive viewport options." -keywords: ["preview"] +description: "Preview changes to your site in real time as you edit, with continuous updates and responsive viewport options." +keywords: ["editor", "preview", "live preview"] --- -Preview your documentation site as you edit. Live preview shows your pages exactly as they appear when published, updating in real time as you make changes to content, navigation, and configuration. +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. ## Open live preview -Click the play button in the toolbar to open a live preview in a new tab. +Click the live preview button in the toolbar to open a live preview in a new tab. Live preview button on the editor toolbar. Live preview button on the editor toolbar. - Live preview is only available for public documentation. If your documentation requires authentication, the editor displays a "Live preview unavailable" message. + Live preview is only available for public documentation. ## Live preview versus preview deployments -| | Live preview | Preview deployment | -|---------|--------------|-------------------| -| **Speed** | Instant | Requires build time | +| | Live preview | Preview deployment | +|---|---|---| +| **Speed** | Instant | Requires a build | | **Access** | Local URL | Shareable URL | -| **Use case** | View changes while editing | Share with team for review | +| **Use when** | Reviewing changes while editing | Sharing with your team for review | | **Availability** | While the editor is open | As long as the branch exists | -Use live preview for immediate feedback as you work. Create preview deployments when you need to share changes with your team or test on different devices. +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/media.mdx b/editor/media.mdx deleted file mode 100644 index fa3e658c5..000000000 --- a/editor/media.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Add media" -description: "Upload, manage, and embed images and other media assets in your documentation pages using the Mintlify web editor's built-in file manager." -keywords: ["editor","media","images","assets"] ---- - -## Supported file types - -- **Images**: PNG, JPG, JPEG, GIF, WebP (max 20 MB) -- **Videos**: MP4, WebM (max 20 MB) -- **Fonts**: TrueType (TTF), WOFF, WOFF2 -- **Other**: PDF, ICO (favicons) - -## Add media to a page - -### Drag and drop - -Drag and drop media from your computer or the asset manager onto a page. In visual mode, the image or video inserts inline. In Markdown mode, the editor inserts the path at your cursor position. Images save to the root of your `images/` folder, and videos save to the root of your `videos/` folder. - -### Slash command - -Type /image to open the image menu or /video to open the video menu. Upload new media or select from existing files. - -### Embed - -Type /youtube to embed a YouTube video or /loom to embed a Loom video. Paste the video URL and the editor generates an iframe. - -For other embeds, type /embed and switch to **Manual embed** to write custom HTML. - -### Upload files - -Use the file explorer in the sidebar to upload or search for files. Drag and drop files into a folder to organize media assets. - - - File explorer open in the editor sidebar menu. - - File explorer open in the editor sidebar menu. - - -## Format images - -After inserting an image in visual mode, hover over it to reveal a toolbar with formatting options. - -- **Light/dark preview**: Toggle between light and dark mode to see how the image appears in each theme. -- **Alignment**: Set the image alignment to left, center, right, or full-width. -- **Frame**: Wrap the image in a `` component to add a border and background. -- **Settings**: Replace the image or update its alt text. - -## Manage assets - -### Organize with folders - -Click the **+** button in the file explorer to create a new folder. Drag and drop files and folders in the file tree to reorganize them. - -### Rename and edit assets - -Hover over an asset and click the **...** button to rename the file or update its alt text. - -### Delete assets - -Hover over an asset and click the delete button. - -## Best practices - -- **Use descriptive names**: Name files clearly, like `api-dashboard-light.png` instead of `img1.png`. -- **Add alt text**: Provide descriptive alt text for accessibility and SEO. -- **Organize with folders**: Group related assets, such as light and dark mode variants or assets for a specific feature area. -- **Use appropriate formats**: PNG for graphics with transparency, JPG for photos, SVG for icons and logos (you cannot upload SVG files through the editor, but you can add them to your repository via Git). diff --git a/editor/navigation.mdx b/editor/navigation.mdx index ce3c5cab7..b29b42009 100644 --- a/editor/navigation.mdx +++ b/editor/navigation.mdx @@ -1,112 +1,44 @@ --- title: "Organize navigation" -description: "Organize your documentation site structure with the visual navigation editor to create groups, reorder pages, and manage the sidebar layout." +description: "Reorder pages and manage your documentation site structure using drag-and-drop in the Mintlify web editor." keywords: ["editor", "navigation", "sidebar", "structure"] --- -Use the navigation sidebar to organize your documentation. Changes you make in the web editor's navigation tree appear in your site's navigation sidebar and sync to your `docs.json` configuration file. +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. ## Add navigation elements - To add a new navigation element, click **Add new** at the bottom of the navigation tree. +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 plus button next to that element. - - Add new navigation element. - Add new navigation 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. -To add a navigation element nested inside another element, click the plus button next to the name of the top-level element. +Right-click a **page** to open its settings or delete it. -After you create an element, drag-and-drop it to reorder or nest it within other elements. Hover over an element then click the gear icon to configure its properties, or right-click an element to access additional options like duplicate, convert to another element, or delete. - -To ungroup pages within a group or other navigation element, right-click then click **Ungroup**. All pages within the ungrouped element move to the root level of your navigation. +Right-click a **navigation element** to open its settings, convert it to a different element type, duplicate it, add a page inside it, add a group inside it, ungroup it, or delete it. - Some elements cannot nest inside other elements. For example, tabs cannot nest inside groups. The web editor prevents you from nesting invalid elements. + Some elements cannot nest inside other elements. For example, tabs cannot nest inside groups. The editor prevents you from creating invalid combinations. -## Organize into sections - -Choose the right navigation structure for your documentation's scope and audience. - -### When to use pages - -Use pages for individual documentation files. Pages are the core building blocks of your navigation—every piece of content lives on a page. Add pages to your navigation to make them visible in your site's sidebar. - -Pages can exist at the root level, within groups, tabs, anchors, dropdowns, or menus. - -Files not included in your navigation are [hidden](/organize/hidden-pages) from your published documentation. - -### When to use groups - -Use groups to organize related pages into collapsible sections. Groups help users scan your navigation by clustering similar content together, like grouping all authentication-related pages or all API endpoint references. - -Groups can nest within other groups to create a hierarchical organization. Groups can exist within tabs, anchors, dropdowns, or at the root level. - -### When to use tabs - -Use tabs to create separate top-level sections with horizontal navigation at the top of your site. Tabs work well when you have distinct areas like API Reference, Guides, and SDKs that users need to switch between. - -Tabs can contain pages, groups, and menu items. Configure tabs to add icons or link to external resources. - -### When to use anchors - -Use anchors to create persistent navigation items at the top of your sidebar. Anchors help when you want to section your content or provide quick access to external resources without switching tabs. - -Anchors can contain pages and groups, or link to external URLs. - -**Global anchors:** - -Create global anchors that appear on all pages regardless of which section users are viewing. Global anchors must link to external URLs and are useful for resources like blogs, status pages, or support links. - -### When to use dropdowns - -Use dropdowns to create an expandable menu at the top of your sidebar. Dropdowns work well when you have multiple related sections that users might want to explore but don't need constant visibility like tabs. - -Dropdowns can contain pages and groups, or link to external URLs. - -### When to use menus - -Use menus to add dropdown navigation items within a tab. Menus help users navigate directly to specific pages from the top navigation bar. - -Menus can contain pages and groups. - -### When to use products - -Use products when you have multiple distinct product offerings that each need their own documentation. Products create a switcher menu that lets users navigate between different product documentation sets. - -Each product can have its own navigation structure with tabs, pages, and groups. - -### When to use versions - -Use versions when you maintain multiple versions of your documentation simultaneously, like v1.0, v2.0, and v3.0 of an API. Versions create a switcher menu that lets users select which version they want to view. - -Each version can have different content and navigation structure. - -### When to use languages - -Use languages when you provide documentation in multiple languages. Languages create a switcher menu that lets users view documentation in their preferred language. - -Each language maintains the same navigation structure with translated content. - -## Customize appearance - -**Add icons:** +## Navigation elements -1. Hover over a navigation item. -2. Click the gear icon. -3. Click the icon field. +Choose the right structure for your content: -**Add tags:** +- **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. -1. Hover over a navigation item. -1. Click the gear icon. -1. Click the tag field. -1. Enter a tag like "NEW" or "BETA" that highlights important items. +## Configure elements -**Control visibility:** +Hover over any navigation element and click the gear icon to set: -Hide the content within a navigation element without deleting it from your repository. +- **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. -1. Right-click any item. -1. Click the toggle by the **Hide** label. diff --git a/editor/pages.mdx b/editor/pages.mdx index fba13577d..5427829f5 100644 --- a/editor/pages.mdx +++ b/editor/pages.mdx @@ -1,20 +1,15 @@ --- title: "Create and edit pages" -description: "Create new pages, edit existing content, and organize documentation structure in the Mintlify web editor with drag-and-drop page management." -keywords: ["editor","content","pages","files"] +description: "Create pages, edit content, upload media, and manage files in the Mintlify editor." +keywords: ["editor", "content", "pages", "files", "create", "edit", "media", "images", "video"] --- ## Navigate files -Browse your documentation pages in the **Navigation** tab of the left panel. - -- Click navigation elements to expand or collapse them. -- Click pages to open them in the editor. -- Click the search icon or press Cmd + K (macOS) or Ctrl + K (Windows) to search for files and content. Search finds matches in both filenames and page content. -- Click the hide sidebar button in the toolbar to collapse the sidebar and give the editor more space. +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 navigation tab lists pages by their titles. The files tab lists pages by their filename and extension. + API specification files (OpenAPI and AsyncAPI) are read-only in the web editor. To update a spec file, edit it in your preferred code editor and push the changes to your documentation repository. ## Create new pages @@ -25,120 +20,97 @@ Browse your documentation pages in the **Navigation** tab of the left panel. ## Edit content -Switch between visual and Markdown mode with the toggle in the toolbar. The web editor saves your changes when switching modes. - - - 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. - +Switch between visual and Markdown mode with the toggle in the toolbar. - Mode toggle in the toolbar. - - Mode toggle in the toolbar. + The mode toggle in the editor toolbar. + The mode toggle in the editor toolbar. -### Visual 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. Other shortcuts: -Edit content with real-time previews that show how the content looks when published. The editor uses your browser's built-in spellcheck to highlight misspelled words as you type. +- **Insert a link**: Select text and press Cmd + K (macOS) or Ctrl + K (Windows), or drag a page from the navigation tree into the editor to create a link with the page title. +- **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. -- **Add text**: Type in the editor to see how the text appears when published. -- **Format text**: Use the toolbar to bold, italicize, or apply other formatting to text. -- **Add components**: Press / to open the component menu and select components. -- **Add images**: Use the image component from the / menu or type /image. -- **Add videos**: Type /video to upload or select a video. -- **Add embedded content**: Type /youtube or /loom to embed videos, or /embed for custom HTML. See [Add media](/editor/media) for details. -- **Add Mermaid diagrams**: Type /mermaid to insert a Mermaid diagram with an interactive preview, zoom/pan controls, and code editor. -- **Add snippets**: Type /snippet to search for and insert a reusable snippet. The editor adds the required import statement automatically. -- **Add math equations**: Type /inline-math for an inline LaTeX equation or /block-math for a centered block equation. [Enable LaTeX](/editor/configurations) in your site settings first. -- **Add prompt blocks**: Type /prompt 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 emojis**: Type : followed by a keyword to open the emoji picker. Use arrow keys to navigate the grid and press Enter to insert the selected emoji. The picker searches emoji names, tags, and shortcodes. -- **Insert links**: Select text and press Cmd + K, or drag a page from the navigation tree into the editor to create a link with the page title. +**Markdown mode** gives you direct access to the MDX source. Use it for precise control over component properties and frontmatter. -See [Components](/components) for the complete list of available components. + + API specification files (OpenAPI and AsyncAPI) are read-only in the web editor. Edit them in your code editor and push the changes to your repository. + -### Markdown mode +For a full list of components, see [Components](/components). For MDX syntax, see [Format text](/create/text) and [Format code](/create/code). -Edit the MDX source code. +### Block actions -- **Direct MDX editing**: Write MDX and Markdown syntax for precise control over content. -- **Component properties**: Set component properties and configurations. -- **Frontmatter**: Edit page metadata at the top of the file. +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: -See [Format text](/create/text) and [Format code](/create/code) for more information on MDX syntax. +- **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. -## Configure pages + + The block actions menu in visual mode. + The block actions menu in visual mode. + -Configure page settings to control how pages appear in navigation, search results, and your site layout. +### Table of contents -Hover over a page, then click the gear icon. You can also right-click a file and select **Settings**. +In visual mode, the editor shows a minimap on the right side of the page that reflects the heading structure of your document. Hover over the minimap to expand it into a full table of contents. Click any heading to scroll to that section. - - A page highlighted in the sidebar so that the settings gear icon is visible. - A page highlighted in the sidebar so that the settings gear icon is visible. - +### Code block options + +When editing a code block in visual mode, you can: -### Customize navigation appearance +- **Highlight or focus lines**: Select text within the code block, then use the toolbar that appears to mark lines as highlighted or focused. Highlighted lines are visually emphasized; focused lines dim everything else. +- **Mark diff lines**: Select lines and use the toolbar to mark them as additions (`+`) or removals (`-`). +- **Wrap**: Toggle line wrapping in the code block settings. +- **Expandable**: Make the code block collapsible so readers can expand it on demand. -Control how the page appears in your site's navigation sidebar. +## Review changes before publishing -- **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. +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. -### Optimize for search and sharing +Diff view is read-only. Click the button next to the mode toggle to return to editing. -Help users find your page and improve how it appears when shared. +## Manage pages + +- **Move**: Drag and drop pages to reorder them in navigation. +- **Rename**: Right-click a page and select **Rename**. +- **Duplicate**: Right-click a page and select **Duplicate**. +- **Delete**: Right-click a page and select **Delete**. The page is removed from navigation automatically. -- **Description**: Write a brief summary. Appears in search results and SEO meta tags. -- **Keywords**: Add relevant search terms to help users discover this page. -- **OG Image URL**: Set a custom preview image for social media shares and link previews. +### Pages deleted via Git -### Control page layout +If a teammate deletes a page through Git while you have it open, the editor enters read-only mode and shows a banner. Your content is preserved so you can copy it before navigating away. -Choose how the page displays to match your content needs. +## Configure pages -- **Standard layout** (`default`): Default page with sidebar navigation and table of contents. -- **Full-width layout** (`wide`): Hides table of contents to allow wider layouts for tables, diagrams, or other content. -- **Centered layout** (`center`): Hides sidebar and table of contents for better readability of text-heavy pages like changelogs. -- **Custom width** (`custom`): Minimal layout with only the top navbar for landing pages or other unique layouts. +Hover over a page and click the gear icon, or right-click and select **Settings**, to configure: -## Manage pages +- **Title**, **Slug**, and **Sidebar title**: Control how the page appears in navigation and its URL. +- **Description** and **Keywords**: Improve search and SEO. +- **Layout**: Choose from standard, wide, centered, or custom. -### Move pages +For details on each setting, see [Pages](/organize/pages). -Drag and drop pages to reorder them in your navigation or move files between folders in the file tree. +## Add media -### Rename pages +### Images and videos -In the file explorer, right-click a file then click **Rename**. The editor preserves the file extension automatically. You only need to enter the name for the page. +Type /image to upload a new image or select an existing one from your repository. Type /video to upload or select a video. -### Duplicate pages +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/`. -Right-click a page and select **Duplicate**. +### Light and dark image variants -### Delete pages +After inserting an image in visual mode, hover over it to reveal the image toolbar. Use **Light/dark variants** to upload separate images for light and dark mode. -Right-click a page and select **Delete**. Deleting a page removes it from your navigation automatically. +### Embed external media -### Hide pages +- **YouTube**: Type /youtube and paste the video URL. +- **Loom**: Type /loom and paste the video URL. +- **Vimeo**: Type /vimeo and paste the video URL. +- **Custom HTML**: Type /embed and switch to **Manual embed**. -To remove a page from navigation without deleting the file, enable the **Hidden** toggle in the page settings. A hidden page remains in your repository and users can still access the page by navigating directly to the page's URL. You can unhide a page in the page settings or add it to your `docs.json` navigation. \ No newline at end of file +For more on formatting images and using the Frame component, see [Images and embeds](/create/image-embeds). diff --git a/editor/publish.mdx b/editor/publish.mdx deleted file mode 100644 index a06d05ed2..000000000 --- a/editor/publish.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "Publish changes in the web editor" -sidebarTitle: "Publish" -description: "Save drafts, stage changes, and publish updates to your live documentation site from the Mintlify web editor with one-click deployment." -keywords: ["editor", "publish", "changes", "branches", "pull requests"] ---- - -## Publishing workflows - -The editor supports two workflows for publishing documentation updates. The workflow you use depends on your repository's branch protection rules and the branch you work on. - -**Create pull requests**: If your repository has a branch protection rule that requires pull requests before changes can merge into your deployment branch, the editor creates a pull request when you publish changes. - - - When you create a pull request from the editor, the Mintlify agent generates a title and description based on your changes. You can edit the generated title and description before creating the pull request. - - -**Publish directly**: If your repository has no branch protection rules, your changes merge to the deployment branch and deploy immediately when you publish. - -| Branch type | Branch protection | Publishing workflow | -|-------------|-------------------|------------------------------| -| Deployment branch | None | Commits and deploys changes | -| Deployment branch | Pull requests required | Creates a pull request | -| Feature branch | None | Merges changes to deployment branch and deploys changes | -| Feature branch | Pull requests required | Creates a pull request | - - - 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. - - -## Save changes - -As you edit, the editor tracks your changes. - -- New or deleted files. -- Content edits in pages. -- Navigation structure changes. -- Media uploads and organization. -- Configuration updates. - -When you work on your deployment branch, changes automatically save. - - - Web editor toolbar showing one pending change. - Web editor toolbar showing one pending change. - - -When you work on a feature branch, save changes to the branch. - - -Web editor toolbar showing one pending change and the Save in branch button on a feature branch. -Web editor toolbar showing one pending change and the Save in branch button on a feature branch. - - -To discard changes, click **Undo changes** beside a filename in the files changed dropdown. - -## Review branch changes - -When you work on a feature branch, the publish panel shows all file changes between your branch and the deployment branch under **Saved in branch**. This includes changes saved by you and any teammates working on the same branch. - -Click a file in the list to open a diff view showing changes between the branch and published content. Documentation files open in a visual diff, and other file types open in a source diff. Use this to review the full scope of changes on a branch before publishing. - -Files that can't display a diff, such as images or removed files, appear in the list but aren't clickable. - -## 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. - -If there are no pending changes or a pull request for the current branch is already open, the **Publish** button is unclickable. - - - Your live documentation site updates after Mintlify builds and deploys your published changes. This typically takes 30 seconds to a few minutes. Check the deployment status of your changes on your [dashboard](https://dashboard.mintlify.com). - - -## Resolve conflicts - -Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. - -### What causes conflicts - -Conflicts happen when you try to merge branches with incompatible changes to the same files. - -- You and another team member edit the same lines in a file on different branches. -- You move, rename, or delete files on one branch and modify them differently on another branch. - -### Resolve conflicts - -The editor displays warnings when conflicts prevent operations like publishing or switching branches. To resolve conflicts, follow the instructions in the editor to choose which changes to keep. - -## Commit signing - -Sign commits with your GitHub account by authorizing it in your [account settings](https://dashboard.mintlify.com/settings/account). Without authorization, the Mintlify GitHub App signs commits made in the web editor. - -Attributing commits to your account maintains an accurate history of who made changes to your documentation. diff --git a/editor/share-a-preview.mdx b/editor/share-a-preview.mdx new file mode 100644 index 000000000..c988c9034 --- /dev/null +++ b/editor/share-a-preview.mdx @@ -0,0 +1,35 @@ +--- +title: "Share a preview" +description: "Share preview deployments and editor links to gather feedback on documentation changes before publishing." +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 where your changes are rendered exactly as they'll 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 popover, 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 — no need to reshare. + +### 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://dashboard.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://dashboard.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath} +``` + +For example: `https://dashboard.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx` + diff --git a/editor/tutorial.mdx b/editor/tutorial.mdx new file mode 100644 index 000000000..006728914 --- /dev/null +++ b/editor/tutorial.mdx @@ -0,0 +1,63 @@ +--- +title: "How to use the editor" +description: "A complete walkthrough of the editor workflow: create a branch, edit pages, preview your changes, and publish." +keywords: ["editor", "tutorial", "branch", "publish"] +--- + +This tutorial walks you through a complete content update using the editor. You'll create a branch, make a change, share a preview for review, and publish your changes. + + + + A branch is a temporary copy of your content. It's where you make your changes without affecting your live site. + + Think of branches like drafts. You can merge them into your live site or safely discard them if you choose not to make the changes. + + Working on a branch keeps your edits separate from your live site until you're ready to share the content with your users. + + 1. In the editor toolbar, click the branch name (usually `main`). + + Branch name emphasized in the editor toolbar. + Branch name emphasized in the editor toolbar. + + 1. Click **Create new branch**. + 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. + + + 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 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. + + + The add page menu opened beside a group in the editor. + The add page menu opened beside a group in the editor. + + + + + 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 your site is built from. + + 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. + + 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 **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. + + + + Share your pull request with your team to review your changes. + + + When your changes are approved, merge your pull request into the main branch. Your changes deploy to your live site. + + diff --git a/images/editor/add-page-dark.png b/images/editor/add-page-dark.png new file mode 100644 index 000000000..cc5067b49 Binary files /dev/null and b/images/editor/add-page-dark.png differ diff --git a/images/editor/add-page-light.png b/images/editor/add-page-light.png new file mode 100644 index 000000000..aa944cf0e Binary files /dev/null and b/images/editor/add-page-light.png differ diff --git a/images/editor/block-actions-dark.png b/images/editor/block-actions-dark.png new file mode 100644 index 000000000..acdc83e1a Binary files /dev/null and b/images/editor/block-actions-dark.png differ diff --git a/images/editor/block-actions-light.png b/images/editor/block-actions-light.png new file mode 100644 index 000000000..0f22dd4e0 Binary files /dev/null and b/images/editor/block-actions-light.png differ diff --git a/images/editor/component-menu-dark.png b/images/editor/component-menu-dark.png deleted file mode 100644 index 235000d8b..000000000 Binary files a/images/editor/component-menu-dark.png and /dev/null differ diff --git a/images/editor/component-menu-light.png b/images/editor/component-menu-light.png deleted file mode 100644 index f510faf62..000000000 Binary files a/images/editor/component-menu-light.png and /dev/null differ diff --git a/images/editor/configurations-dark.png b/images/editor/configurations-dark.png index 23426c00b..d889295e5 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 20e2f9c1b..6406aa9e8 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 new file mode 100644 index 000000000..8a304a198 Binary files /dev/null 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 new file mode 100644 index 000000000..49d032e8a Binary files /dev/null and b/images/editor/create-branch-light.png differ diff --git a/images/editor/file-type-dark.png b/images/editor/file-type-dark.png deleted file mode 100644 index 3d96c6ef1..000000000 Binary files a/images/editor/file-type-dark.png and /dev/null differ diff --git a/images/editor/file-type-light.png b/images/editor/file-type-light.png deleted file mode 100644 index 13d89a2d3..000000000 Binary files a/images/editor/file-type-light.png and /dev/null differ diff --git a/images/editor/files-menu-dark.png b/images/editor/files-menu-dark.png deleted file mode 100644 index 51f4267a4..000000000 Binary files a/images/editor/files-menu-dark.png and /dev/null differ diff --git a/images/editor/files-menu-light.png b/images/editor/files-menu-light.png deleted file mode 100644 index e3936f754..000000000 Binary files a/images/editor/files-menu-light.png and /dev/null differ diff --git a/images/editor/live-preview-dark.png b/images/editor/live-preview-dark.png index b867b17fc..019466863 100644 Binary files a/images/editor/live-preview-dark.png and b/images/editor/live-preview-dark.png differ diff --git a/images/editor/live-preview-light.png b/images/editor/live-preview-light.png index 82a846e6c..ee314351c 100644 Binary files a/images/editor/live-preview-light.png and b/images/editor/live-preview-light.png differ diff --git a/images/editor/markdown-mode-dark.png b/images/editor/markdown-mode-dark.png deleted file mode 100644 index 8722f2cf8..000000000 Binary files a/images/editor/markdown-mode-dark.png and /dev/null differ diff --git a/images/editor/markdown-mode-light.png b/images/editor/markdown-mode-light.png deleted file mode 100644 index 651f7417e..000000000 Binary files a/images/editor/markdown-mode-light.png and /dev/null differ diff --git a/images/editor/mode-toggle-dark.png b/images/editor/mode-toggle-dark.png index 4427aab4c..790198509 100644 Binary files a/images/editor/mode-toggle-dark.png and b/images/editor/mode-toggle-dark.png differ diff --git a/images/editor/mode-toggle-light.png b/images/editor/mode-toggle-light.png index 170693bca..a9248c55c 100644 Binary files a/images/editor/mode-toggle-light.png and b/images/editor/mode-toggle-light.png differ diff --git a/images/editor/preview-url-dark.png b/images/editor/preview-url-dark.png new file mode 100644 index 000000000..e995bd89f Binary files /dev/null and b/images/editor/preview-url-dark.png differ diff --git a/images/editor/preview-url-light.png b/images/editor/preview-url-light.png new file mode 100644 index 000000000..fc78fafea Binary files /dev/null and b/images/editor/preview-url-light.png differ diff --git a/images/editor/publish-flow-dark.png b/images/editor/publish-flow-dark.png deleted file mode 100644 index 67dcb3456..000000000 Binary files a/images/editor/publish-flow-dark.png and /dev/null differ diff --git a/images/editor/publish-flow-light.png b/images/editor/publish-flow-light.png deleted file mode 100644 index 4f9dec1ec..000000000 Binary files a/images/editor/publish-flow-light.png and /dev/null differ diff --git a/images/editor/publish-menu-dark.png b/images/editor/publish-menu-dark.png new file mode 100644 index 000000000..6cb0a50e4 Binary files /dev/null and b/images/editor/publish-menu-dark.png differ diff --git a/images/editor/publish-menu-light.png b/images/editor/publish-menu-light.png new file mode 100644 index 000000000..86a99e3c3 Binary files /dev/null and b/images/editor/publish-menu-light.png differ diff --git a/images/editor/pull-request-dark.png b/images/editor/pull-request-dark.png deleted file mode 100644 index 230592d81..000000000 Binary files a/images/editor/pull-request-dark.png and /dev/null differ diff --git a/images/editor/pull-request-light.png b/images/editor/pull-request-light.png deleted file mode 100644 index 5bbe34a2d..000000000 Binary files a/images/editor/pull-request-light.png and /dev/null differ diff --git a/images/editor/rename-dark.png b/images/editor/rename-dark.png deleted file mode 100644 index 9deb71296..000000000 Binary files a/images/editor/rename-dark.png and /dev/null differ diff --git a/images/editor/rename-light.png b/images/editor/rename-light.png deleted file mode 100644 index 46195e44e..000000000 Binary files a/images/editor/rename-light.png and /dev/null differ diff --git a/images/editor/visual-mode-dark.png b/images/editor/visual-mode-dark.png deleted file mode 100644 index 11508e71b..000000000 Binary files a/images/editor/visual-mode-dark.png and /dev/null differ diff --git a/images/editor/visual-mode-light.png b/images/editor/visual-mode-light.png deleted file mode 100644 index 0443f40bf..000000000 Binary files a/images/editor/visual-mode-light.png and /dev/null differ diff --git a/redirects.json b/redirects.json index 9095a258e..30b79a8e0 100644 --- a/redirects.json +++ b/redirects.json @@ -418,5 +418,17 @@ { "source": "/settings/global", "destination": "/organize/settings" + }, + { + "source": "/editor/git-essentials", + "destination": "/editor/branching-and-publishing" + }, + { + "source": "/editor/publish", + "destination": "/editor/branching-and-publishing" + }, + { + "source": "/editor/media", + "destination": "/editor/pages" } ]