Skip to main content
A Git diff shows which lines changed. A preview shows what those changes do to the documentation site. When the Mintlify GitHub App has access to your repository, pull requests to your deployment branch get a preview deployment: a temporary copy of your site with the changes applied. New commits update the preview, so reviewers can follow the same link throughout the pull request.

​
Find the preview

Open the pull request and look for the Mintlify bot’s comment with the preview link. The deployment may still be building when the pull request first opens, so check its status if the link isn’t ready yet. If no preview appears:
  1. Confirm that the pull request targets the configured deployment branch.
  2. If the pull request comes from a fork, look for a Mintlify Preview (fork) check that says Action required. Fork previews need approval before they build, because they run the contributor’s code.
  3. Check that the Mintlify GitHub App can access the repository.
  4. Open the Previews page in your Mintlify dashboard to see the build status.
You can also create a preview for any branch, with or without a pull request, from the Previews page.

​
Review what readers will experience

Start with every page changed by the pull request. The preview widget, a floating button in the bottom-right corner of the preview, lists every added, modified, and removed page and links straight to each one. For each page, check:
  • The page renders without broken MDX or missing media
  • The edited section makes sense with the paragraphs around it
  • Links and interactive components behave as expected
  • Headings and the table of contents describe the page clearly
Then check the effects beyond those pages. A small docs.json edit can move several pages, change a label, or remove something from navigation. Follow the relevant path through the sidebar instead of checking only the URL you were given. For layout-heavy changes, resize the browser or check a mobile viewport. You don’t need to test every screen size on every copy edit; focus the review on what the change could plausibly affect.

​
Give reviewers a specific task

Share the preview with a short review request. For example:
Please check the new authentication flow from Create a token through Test the request. In particular, does the choice between service and user tokens make sense before step one?
That is more useful than “Thoughts?” Reviewers know where to start and what kind of feedback you need. Preview URLs are publicly accessible by default, even though they show unpublished content. Some organizations require a Mintlify login to view previews. If yours does and you need a review from someone outside your organization, you can password-protect an individual preview and share the password with them instead.

​
Treat the preview and diff as a pair

The preview shows what readers will see. It won’t show things that never render, like a comment in the MDX source, a leftover debug note in a snippet that no page uses, or an API key pasted into a file. Review the Git diff for source changes and the preview for the reader experience. Next up: Collaborating with your team—make reviews useful and handle overlapping work without losing changes.