mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
cf7bc11deb
Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
110 lines
5.4 KiB
Plaintext
110 lines
5.4 KiB
Plaintext
---
|
|
title: "Collaborate in the web editor"
|
|
sidebarTitle: "Collaborate"
|
|
description: "Work together on documentation with branches, pull requests, preview deployments, comments, and shareable editor links."
|
|
keywords: ["editor", "collaboration", "branches", "pull requests", "preview deployments", "share links", "comments"]
|
|
---
|
|
|
|
Collaborate with your team on documentation using branch-based workflows, pull requests, preview deployments, and inline comments.
|
|
|
|
If you aren't familiar with Git, see [Git essentials for the web editor](/editor/git-essentials).
|
|
|
|
## Branch-based collaboration
|
|
|
|
Use branches to work on documentation updates in parallel without affecting your live site.
|
|
|
|
### Why use branches
|
|
|
|
- **Isolate changes**: Work on updates without affecting your live documentation.
|
|
- **Review before publishing**: Get feedback from team members before changes go live.
|
|
- **Parallel work**: Multiple team members can work on different branches simultaneously.
|
|
|
|
## Add comments
|
|
|
|
Leave comments on documentation pages to discuss changes, ask questions, or provide feedback to your team. Comments help you collaborate directly in the editor without switching to external tools.
|
|
|
|
### Create a comment
|
|
|
|
1. Select text in the editor or click where you want to add a comment.
|
|
2. Click the comment icon that appears or use the keyboard shortcut.
|
|
3. Type your comment and press **Send**.
|
|
|
|
Comments appear as threads in the editor sidebar. Team members can reply to comments to continue the discussion.
|
|
|
|
### Resolve comments
|
|
|
|
Mark comments as resolved when the discussion is complete or the issue is addressed. Resolved comments are hidden from view but remain accessible in the comment history.
|
|
|
|
To resolve a comment thread, click **Resolve** in the comment thread.
|
|
|
|
### Comments in pull requests
|
|
|
|
Unresolved comments automatically sync to your GitHub pull request description. This keeps your team informed about open discussions without leaving GitHub.
|
|
|
|
The pull request description includes:
|
|
- A summary of unresolved comment threads and participating users
|
|
- Links to each commented file
|
|
- Preview text from each comment
|
|
- Direct links back to the editor to view and respond to comments
|
|
|
|
Comments sync to the pull request description after a short delay (approximately 5 seconds) to batch multiple changes together. When you resolve comments or add new ones, the pull request description updates automatically.
|
|
|
|
## Recommended workflow
|
|
|
|
Use pull requests to propose changes and collaborate with your team before merging to your live documentation. This workflow ensures your team reviews changes before publishing and maintains a clear history of updates.
|
|
|
|
<Steps>
|
|
<Step title="Create a pull request">
|
|
Create a pull request from the editor when you're ready to publish your changes. See <a href="/editor/publish">Publish changes in the web editor</a> for more information on using pull requests.
|
|
</Step>
|
|
<Step title="Review pull requests">
|
|
Review pull requests in your Git provider like GitHub or GitLab. Unresolved editor comments appear in the pull request description with links back to the editor.
|
|
</Step>
|
|
<Step title="Respond to feedback">
|
|
When reviewers request changes, make the requested changes and save your changes. Additional changes automatically push to the existing pull request.
|
|
</Step>
|
|
<Step title="Merge pull requests">
|
|
Merge your pull request after addressing all requested changes, required reviewers approve the pull request, and any automated checks pass.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Preview deployments
|
|
|
|
Preview deployments create temporary URLs where you can see your rendered changes before they go live. Use preview deployments to gather feedback on how changes.
|
|
|
|
Every time you save changes to a branch, the preview deployment updates automatically.
|
|
|
|
### Access preview deployments
|
|
|
|
1. Click **Publish** in the editor tool bar.
|
|
2. Click the preview URL open the preview deployment in a new tab. The URL format is `organization-branch-name.mintlify.app`.
|
|
|
|
<Frame>
|
|
<img src="/images/editor/share-preview-light.png" className="block dark:hidden" alt="Share button in the editor toolbar" />
|
|
<img src="/images/editor/share-preview-dark.png" className="hidden dark:block" alt="Share button in the editor toolbar" />
|
|
</Frame>
|
|
|
|
### Share previews
|
|
|
|
Share the preview deployment URL with team members to gather feedback. Previews update automatically when you save additional changes.
|
|
|
|
### Preview authentication
|
|
|
|
Preview URLs are publicly accessible by default. Enable preview authentication in the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard to restrict access to authenticated organization members.
|
|
|
|
## Share editor links
|
|
|
|
Share a direct link to a specific page in the editor with your teammates. Use editor links to collaborate on updates and make changes to pages.
|
|
|
|
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 URL format is: `https://dashboard.mintlify.com/{org}/{project}/editor/{branch}?file={filepath}`
|
|
|
|
For example, `https://dashboard.mintlify.com/acme/docs/editor/main?file=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.
|
|
|
|
<Tip>
|
|
When you share a page, tell people which branch you're working on so they can confirm they view the correct version.
|
|
</Tip>
|