From be158147d5cea268d77a8785c9dc5286e7319b82 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 01:31:36 +0000 Subject: [PATCH] docs: document the from option on the admin MCP create_branch tool --- agent-context/context/skills/mintlify/SKILL.md | 2 +- ai/mintlify-mcp.mdx | 8 ++++++-- skill.md | 2 +- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/agent-context/context/skills/mintlify/SKILL.md b/agent-context/context/skills/mintlify/SKILL.md index e2376916d..d5f7b0423 100644 --- a/agent-context/context/skills/mintlify/SKILL.md +++ b/agent-context/context/skills/mintlify/SKILL.md @@ -94,7 +94,7 @@ Use this server when the user wants to edit their Mintlify content, restructure Workflow: use `read`/`search`/`edit_page`/`write_page`/`list_nodes`/`create_node`/`update_node`/`move_node`/`delete_node`/`update_config` with a `branch` to make changes, then call `publish` with the `branch` and a `title` to publish (or `discard` to abandon). Pass the deploy branch to edit it directly. If the project requires a pull request (**Push directly to your deploy branch** is off, branch protection requires pull requests, deploy branch editing is locked, or the connection uses a client or machine-to-machine token), edits to the deploy branch are refused with the reason and change nothing. Call `create_branch` and pass its `branchName` as `branch` instead. Projects with auto publish turned on have no branches: pass the deploy branch, where edits are committed automatically. `create_branch` and other branches are refused there, and pull request requirements don't apply. Key tools: -- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request. +- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Pass `from` to start off another existing branch instead: `create_branch { title: "Add tips page", from: "docs-refresh" }`. On GitHub, GitLab, and Azure Repos, its pull request then targets the `from` branch. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request. - **`list_branches`** — List existing branches; pass any of them as `branch`. Branches that don't exist are refused. - **`list_deployments`** — Discover which project(s) this connection can access. - **`read`** / **`search`**: Fetch a page's MDX or search across pages. `search` returns the most relevant pages with matching `snippets`, plus the full `content` of a confident top result, so `read` a page only when the results are not enough; pass `mode: "all"` (or `regex: true`) to list every page containing a phrase. `read`, `edit_page` and `write_page` take a page path (such as `guides/setup`) or the last segment of an editor URL, which is the page ID with an optional title in front of it. With a page ID from an editor URL, pass that URL's branch as `branch`. `read` returns a `filePath` to pass as `path` to `edit_page` and `write_page`, and a `version`; pass `forEdit: true` to read the live page instead of its saved copy. diff --git a/ai/mintlify-mcp.mdx b/ai/mintlify-mcp.mdx index cebc2f320..4f8788962 100644 --- a/ai/mintlify-mcp.mdx +++ b/ai/mintlify-mcp.mdx @@ -161,11 +161,15 @@ To get your changes published, ask the AI tool to request a review. The AI tool Call `create_branch` with a `title` when your project requires a pull request, or when you want one anyway. Mintlify starts a new branch off your deploy branch, names it `/` the same way the dashboard editor names branches, and seeds it from your published content. The pull request opens with this title. For example, `create_branch { subdomain: "acme", title: "Add tips page" }`. +To start from another existing branch instead, such as a feature branch for a large update, pass its name as `from`. For example, `create_branch { subdomain: "acme", title: "Add tips page", from: "docs-refresh" }`. Mintlify refuses `from` branches that don't exist and creates nothing. + +If your repository is on GitHub, GitLab, or Azure Repos, a branch you start from a branch other than your deploy branch becomes a [sub-branch](/editor/publish#sub-branches), and its pull request targets the `from` branch instead of your deploy branch. + `create_branch` returns the `branchName`, the `baseBranch` and `baseSha` it started from, a `note`, and an `editorUrl` you can open to follow along in the dashboard editor. Pass the `branchName` as `branch` in every later call. To work on an existing branch, pass its name as `branch`. Call `list_branches` to discover branches in a project's repository. Mintlify refuses calls on branches that don't exist. -On a branch, Mintlify commits your edits automatically, about 15 seconds after the last change. This includes page content, navigation changes, and `docs.json` updates. The first commit opens a pull request against your deploy branch. The pull request opens as a draft if [Create draft pull requests by default](/editor/settings#create-draft-pull-requests-by-default) is on. Nothing reaches your deploy branch until someone merges the pull request. +On a branch, Mintlify commits your edits automatically, about 15 seconds after the last change. This includes page content, navigation changes, and `docs.json` updates. The first commit opens a pull request against your deploy branch, or against the `from` branch for a sub-branch. The pull request opens as a draft if [Create draft pull requests by default](/editor/settings#create-draft-pull-requests-by-default) is on. Nothing reaches your deploy branch until someone merges the changes into it. `discard` on a branch other than your deploy branch deletes the branch and closes its pull request, even if the branch has commits. This matches deleting a branch in the dashboard editor. `discard` only deletes branches you created in Mintlify. For any other branch, it refuses and changes nothing. @@ -320,7 +324,7 @@ These tools appear only when your project [requires review before publishing](/e ### Branches and publishing - **`list_deployments`**: List the projects your connection can access, returning each `{subdomain, name, projectType}`. `projectType` is `site` for a docs site or `workspace` for a base. Call this to discover which `subdomain` to pass. -- **`create_branch`**: Start a new branch off your deploy branch with a `title` that also names its pull request. Returns the `branchName` to pass as `branch`. See [Work on a branch](#work-on-a-branch). You don't need it to [edit the deploy branch directly](#edit-the-deploy-branch-directly). +- **`create_branch`**: Start a new branch off your deploy branch, or off the existing branch you pass as `from`, with a `title` that also names its pull request. Returns the `branchName` to pass as `branch`. See [Work on a branch](#work-on-a-branch). You don't need it to [edit the deploy branch directly](#edit-the-deploy-branch-directly). - **`list_branches`**: List Git branches available for a project's repository, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Pass any of them as `branch`. - **`status`**: List the edited files, changed `docs.json` keys, and pending navigation diff on `branch`, or on your deploy branch when you omit it. On the deploy branch, lists only your changes. - **`diff`**: List all changes between `branch` and your deploy branch. Each changed file and `docs.json` entry includes `authors` and `byYou`. `authors` lists the members whose unpublished edits the entry contains. `byYou` is `true` when the entry includes your own edits. Use `byYou` to tell your changes apart from a colleague's on a shared branch. diff --git a/skill.md b/skill.md index 6a374a95a..ee1dca093 100644 --- a/skill.md +++ b/skill.md @@ -96,7 +96,7 @@ Use this server when the user wants to edit their Mintlify content, restructure Workflow: use `read`/`search`/`edit_page`/`write_page`/`list_nodes`/`create_node`/`update_node`/`move_node`/`delete_node`/`update_config` with a `branch` to make changes, then call `publish` with the `branch` and a `title` to publish (or `discard` to abandon). Pass the deploy branch to edit it directly. If the project requires a pull request (**Push directly to your deploy branch** is off, branch protection requires pull requests, deploy branch editing is locked, or the connection uses a client or machine-to-machine token), edits to the deploy branch are refused with the reason and change nothing. Call `create_branch` and pass its `branchName` as `branch` instead. Projects with auto publish turned on have no branches: pass the deploy branch, where edits are committed automatically. `create_branch` and other branches are refused there, and pull request requirements don't apply. Key tools: -- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request. +- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Pass `from` to start off another existing branch instead: `create_branch { title: "Add tips page", from: "docs-refresh" }`. On GitHub, GitLab, and Azure Repos, its pull request then targets the `from` branch. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request. - **`list_branches`** — List existing branches; pass any of them as `branch`. Branches that don't exist are refused. - **`list_deployments`** — Discover which project(s) this connection can access. - **`read`** / **`search`**: Fetch a page's MDX or search across pages. `search` returns the most relevant pages with matching `snippets`, plus the full `content` of a confident top result, so `read` a page only when the results are not enough; pass `mode: "all"` (or `regex: true`) to list every page containing a phrase. `read`, `edit_page` and `write_page` take a page path (such as `guides/setup`) or the last segment of an editor URL, which is the page ID with an optional title in front of it. With a page ID from an editor URL, pass that URL's branch as `branch`. `read` returns a `filePath` to pass as `path` to `edit_page` and `write_page`, and a `version`; pass `forEdit: true` to read the live page instead of its saved copy.