Documentation pull requests are easier to review when teammates can open the rendered site, not only the MDX diff. The docs.page GitHub App watches pull requests on your repository and posts a comment with a link to the live preview for that PR's head branch.
The GitHub App is a one-time install on repositories that use public GitHub hosting. After installation, docs.page comments on pull requests with a preview URL built from branch preview routing.
You do not configure webhooks or add secrets to docs.json. The app uses GitHub pull request events and docs.page's existing ~ref URL model to serve the same MDX and configuration as production, just from the PR branch.
When someone opens or updates a pull request on a connected repository, the GitHub App posts a comment with a link to the live documentation preview for that PR.
The link targets the PR's head branch through docs.page ref routing. Reviewers click once to open the site as it would look if the branch merged (navigation, theme, search, and MDX components included).
Branch preview serves docs from a specific Git ref when you add a ~{ref} segment after the repository name:
https://docs.page/{owner}/{repo}~{ref}
https://docs.page/{owner}/{repo}~{ref}/{page-path}For pull requests, a numeric ref resolves to that PR's head branch through the GitHub API. For example, ~42 opens the docs for pull request #42.
The GitHub App constructs the same ~ref URL in its comment. You can still build or share ref URLs manually; the app removes that step for the common pull request workflow.
If the repository has a custom domain configured, the comment uses that hostname instead of the default docs.page/{owner}/{repo} path. Preview links follow the shorter custom-domain shape:
https://docs.example.com/~{ref}
https://docs.example.com/~{ref}/{page-path}Production, branch previews, and GitHub App comments stay consistent on whichever public URL your readers use.
The GitHub App only works with public repositories, the same constraint as docs.page hosting. Private repositories cannot be served or previewed through docs.page, even with the app installed.
Keep documentation in a public repository, or in a dedicated public docs repo. The GitHub App cannot substitute for hosting on private repos.
-
Open the app listing: Go to docs.page on GitHub and click Install.
-
Select repositories: Choose the organization or account, then install on the public repository that hosts your docs (or on all repositories if you prefer).
-
Open a pull request: Push a branch with documentation changes and open a PR. The app posts a comment with the live preview link for that PR's head branch.
No changes to docs.json are required. To preview before opening a PR, use local preview or share a branch preview URL manually.