From a047e17fa29f804364a40b811dc7377d8b7ce6fd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 9 Apr 2026 01:49:15 +0000 Subject: [PATCH] Update publish workflow docs for editor publish flow Generated-By: mintlify-agent --- editor/collaborate.mdx | 2 +- editor/publish.mdx | 49 +++++++++++++++++++++++++++-------------- guides/branches.mdx | 2 +- guides/git-concepts.mdx | 15 ++++++------- 4 files changed, 42 insertions(+), 26 deletions(-) diff --git a/editor/collaborate.mdx b/editor/collaborate.mdx index 1726f8494..89e650b80 100644 --- a/editor/collaborate.mdx +++ b/editor/collaborate.mdx @@ -34,7 +34,7 @@ Use pull requests to propose changes and collaborate with your team before mergi When reviewers request changes, make the requested changes and save your changes. 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. + After all requested changes are addressed and required reviewers approve the pull request, merge it to deploy your changes. You can merge approved pull requests directly from the editor by clicking **Merge and publish** in the publish popover, or merge in your Git provider. diff --git a/editor/publish.mdx b/editor/publish.mdx index d32caed34..27b49de6e 100644 --- a/editor/publish.mdx +++ b/editor/publish.mdx @@ -7,22 +7,14 @@ 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. +The editor supports multiple 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 | +| Branch type | Branch protection | Available actions | |-------------|-------------------|------------------------------| -| 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 | +| Deployment branch | None | Publish directly | +| Deployment branch | Pull requests required | Create a branch to make changes | +| Feature branch | None | Save in branch, create a pull request | +| Feature branch | Pull requests required | Save in branch, create 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. @@ -56,14 +48,39 @@ To discard changes, click **Undo changes** beside a filename in the files change ## 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. +Click the publish button in the toolbar to open the publish popover. The actions available depend on your branch and branch protection rules. + +- **Publish**: On the deployment branch without branch protections, click **Publish** to commit and deploy your changes immediately. +- **Save in branch**: On a feature branch, click **Save in branch** to commit your changes to the current branch. +- **Create branch**: On a protected deployment branch, click **Create branch** to move your changes to a new branch. +- **Create pull request**: On a feature branch, click **Create pull request** to open a pull request targeting your deployment branch. + + + When you create a pull request from the editor, you can set a title and description before creating it. + -If there are no pending changes or a pull request for the current branch is already open, the **Publish** button is unclickable. +If there are no pending changes, the publish and save actions are disabled. 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). +## Review and merge pull requests + +When a pull request is open for the current branch, the publish popover shows its review status: + +- **Approved**: The pull request has been approved and is ready to merge. +- **Changes requested**: A reviewer requested changes before the pull request can merge. +- **Awaiting review**: The pull request is waiting for a review. + +Click **View request** to open the pull request in your Git provider. + +If the pull request is approved, click **Merge and publish** to merge the pull request and deploy changes to your live documentation directly from the editor. After merging, the editor switches to your deployment branch. + + + If your repository requires approvals before merging, **Merge and publish** is only available after the pull request is approved. + + ## Resolve conflicts Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. diff --git a/guides/branches.mdx b/guides/branches.mdx index e85ab84ab..0e7b44fd2 100644 --- a/guides/branches.mdx +++ b/guides/branches.mdx @@ -79,7 +79,7 @@ Use clear, descriptive names that explain the purpose of a branch. - Select the **Save as commit** button in the top-right of the editor toolbar. This creates a commit and pushes your work to your branch automatically. + Click the publish button in the top-right of the editor toolbar and select **Save in branch**. This creates a commit and pushes your work to your branch automatically. Stage, commit, and push your changes. diff --git a/guides/git-concepts.mdx b/guides/git-concepts.mdx index c1ef81e31..4decfa593 100644 --- a/guides/git-concepts.mdx +++ b/guides/git-concepts.mdx @@ -122,7 +122,8 @@ When you: - **Save changes**: The editor makes a commit with your changes, preserving your work in the project history. - **Create a branch**: The editor creates a new branch in your repository that anyone with access to the repository can use to collaborate and review changes. - **Publish on your deployment branch**: The editor commits and pushes directly to your deployment branch, which publishes your changes immediately. -- **Publish on other branches**: The editor creates a pull request, which allows you to get feedback from others before merging your changes into your deployment branch. +- **Save on other branches**: The editor commits your changes to the branch. You can then create a pull request from the editor to propose merging your changes into the deployment branch. +- **Merge pull requests**: The editor lets you merge approved pull requests directly, deploying your changes without leaving the editor. ## Common workflows @@ -149,13 +150,11 @@ When you: - - To create pull requests from the web editor, you must have a branch protection rule enabled that requires pull requests before changes can merge into your deployment branch. Without branch protection rules, changes on branches merge to your deployment branch when published. - - 1. Create branch from the branch dropdown in the editor toolbar. - 2. Make and save changes on the branch. - 3. Click **Publish** to create a pull request. - 4. Merge the pull request when ready. + 1. Create a branch from the branch dropdown in the editor toolbar. + 2. Make changes on the branch. + 3. Click the publish button and select **Save in branch** to commit your changes. + 4. Click **Create pull request** to propose merging your changes. + 5. After the pull request is approved, click **Merge and publish** to deploy your changes. 1. Create a branch: `git checkout -b feature-name`