Skip to content

docs: clarify how to reach the Previews tab from the dashboard #7074

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 4 commits into
base: main
Choose a base branch
from
+14 −8
Open

docs: clarify how to reach the Previews tab from the dashboard #7074

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b2dd02b
docs: clarify how to reach the Previews tab from the dashboard
mintlify[bot] Aug 24, 2026
3e2b086
docs: collapse Settings + activity dashboard into one step
mintlify[bot] Aug 24, 2026
05d30db
docs: clarify preview restriction requires Enterprise add-on
mintlify[bot] Aug 25, 2026
6f52fca
docs: tighten preview access restriction callout
mintlify[bot] Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions deploy/preview-deployments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@

### Fork pull requests

Pull requests opened from a fork do not generate preview deployments. The Mintlify GitHub App must be installed on a repository to generate a preview, so it cannot read a fork or build a preview against it.

Check warning on line 34 in deploy/preview-deployments.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/preview-deployments.mdx#L34 

In general, use active voice instead of passive voice ('be installed').

A maintainer with write access to the main repository can preview changes from a fork. They can push the forked contributor's branch to a branch in the main repository or merge the fork into an integration branch. The GitHub App can then build a preview for a pull request opened from that branch.

Expand All @@ -39,8 +39,8 @@

You can manually create a preview for any branch.

1. Go to your [dashboard](https://app.mintlify.com/).
2. Click **Previews**.
1. In your dashboard, open the organization dropdown in the upper-left corner and click **Settings** to go to the activity dashboard.
2. Click the **Previews** tab.
3. Click **Create custom preview**.
4. Enter the name of the branch you want to preview.
5. Click **Create preview**.
Expand All @@ -53,8 +53,10 @@

Redeploy a preview to refresh content or retry after a failed deployment.

1. Click the preview from your [dashboard](https://app.mintlify.com/).
2. Click **Redeploy**.
1. In your dashboard, open the organization dropdown in the upper-left corner and click **Settings** to go to the activity dashboard.
2. Click the **Previews** tab.
3. Click the preview you want to redeploy.
4. Click **Redeploy**.

<Frame>
<img src="/images/previews/redeploy-preview-light.png" alt="The Previews menu with the deploy button emphasized by an orange rectangle." className="block dark:hidden" />
Expand All @@ -81,6 +83,10 @@

By default, preview deployments are publicly accessible to anyone with the URL. You can restrict access by requiring organization authentication for all previews or by password-protecting individual previews.

<Info>
Restricting preview access is an Enterprise add-on. It is separate from Pro password protection (which gates production, not previews) and the SSO Login add-on (which gates the dashboard). Contact your account team to enable it.
</Info>

### Require organization authentication

Restrict preview access to authenticated members of your Mintlify organization.
Expand All @@ -96,8 +102,8 @@

Password-protect a specific preview to share it with external reviewers without adding them to your Mintlify organization. This option is available when creating a manual preview and is not shown when organization authentication is already enabled for your deployment.

1. Go to your [dashboard](https://app.mintlify.com/).
2. Click **Previews**.
1. In your dashboard, open the organization dropdown in the upper-left corner and click **Settings** to go to the activity dashboard.
2. Click the **Previews** tab.
3. Click **Create custom preview**.
4. Enter the name of the branch you want to preview.
5. Toggle **Make private** on and enter a password. Passwords must be at least 8 characters.
Expand All @@ -113,7 +119,7 @@

- **Automatic previews**: The preview for a pull request remains available while the PR is open and after it's merged or closed, as long as the source branch still exists. When you delete the branch, the next dashboard sync removes the preview.
- **Manual previews**: Manual previews stay live until you delete them. Redeploying a manual preview refreshes its content against the latest commit on the specified branch.
- **Delete a preview**: In your [dashboard](https://app.mintlify.com/), go to **Previews**, open the preview, and click **Delete** to remove it immediately.
- **Delete a preview**: In your dashboard, open the organization dropdown in the upper-left corner, click **Settings** to go to the activity dashboard, and then click the **Previews** tab. Open the preview and click **Delete** to remove it immediately.

Preview URLs are unique per branch. If you delete a preview and later recreate one for the same branch, Mintlify may issue a new URL.

Expand All @@ -123,7 +129,7 @@

If your preview deployment fails, try these troubleshooting steps.

- **View the build logs**: In your [dashboard](https://app.mintlify.com/), go to **Previews** and click the failed preview. The deployment logs show errors that caused failures.
- **View the build logs**: In your dashboard, open the organization dropdown in the upper-left corner, click **Settings** to go to the activity dashboard, and then click the **Previews** tab. Click the failed preview to see the deployment logs.
- **Check your configuration**:
- Missing `docs.json` at the configured content root. If your `docs.json` is in a subdirectory, confirm the **docs.json is in a subdirectory** setting points to the correct path.
- Invalid `docs.json` syntax (for example, an empty file or a stray trailing comma that breaks JSON parsing).
Expand Down