docs: note large file errors when publishing in the web editor

editor/branching-and-publishing.mdx

@@ -4,13 +4,13 @@
 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.
 
@@ -38,7 +38,7 @@
 - **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.
 
 <Note>
   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).
@@ -48,7 +48,7 @@
 
 **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
 
@@ -70,7 +70,7 @@
 1. Click the branch to switch to it.
 
 <Note>
   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.
 </Note>
 
 <Tip>
@@ -112,13 +112,13 @@
 
 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.
 
 <Tip>
   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.
@@ -136,6 +136,16 @@
 
 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.
 
+### Large files
+
+Publishes are subject to a maximum payload size. If a file in your changes is too large to publish, the editor shows an error identifying the file and blocks the publish.
+
+To resolve the error:
+
+- Compress large media files before adding them. See [Media guidelines](/guides/media) for recommendations.
+- Host videos on an external platform like YouTube or Loom and embed them, rather than committing video files to your repository.
+- Split your changes into smaller publishes so that no single commit exceeds the limit.
+
 ## 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.
@@ -144,13 +154,13 @@
 
 ## 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