Publish

Before you begin

• A public GitHub repository, docs.page only hosts public repos. See Public GitHub hosting.
• Preview and check already passed on your machine
• Git installed and write access to the repository on GitHub

This page covers remote actions on GitHub after local Preview: push your branch, share branch previews, enable PR preview comments, run check in CI, and merge to production.

Commit your documentation changes and push the branch to GitHub so docs.page can read the files from the remote.

• Capture documentation changes in git

  Stage at minimum docs.json, pages under docs/, and any assets you added:

  git add docs.json docs/
  git commit -m "Update documentation"

• Make the branch available on GitHub

  Push the branch to the remote:

  git push -u origin [your-branch-name]

  Use your actual branch name instead of your-branch-name. After the push completes, the branch is available for branch preview URLs and for pull request review.

Share a live preview URL so reviewers can open the rendered site from your branch (navigation, theme, search, and MDX components included) without running the CLI locally.

Replace {ref} in the URL with one of:

• Build a ref URL reviewers can open

  Add ~{ref} immediately after the repository name:

  https://docs.page/{owner}/{repo}~{ref}
  https://docs.page/{owner}/{repo}~{ref}/{page-path}

  Replace {owner} and {repo} with your GitHub organization or user and repository name. Pick the {ref} segment from the table above.

• Confirm the branch site looks right

  Open the URL in a browser and confirm the pages you changed render as expected.

• Share the link in your review thread

  Send the URL to reviewers in your pull request description, chat, or review comments.

Production URLs omit the ~ref segment entirely. For ref URL patterns, numeric PR resolution, and when to use branch preview instead of local preview, see Branch preview.

Install the docs.page GitHub App once so every pull request gets an automatic comment with a live preview link, reviewers do not need to build ref URLs by hand.

• Install the GitHub App once

  Open docs.page on GitHub and click Install.

• Grant access to your public docs repository

  Select your account or organization, then install on the public repository that hosts your docs.

• Get automatic preview links on pull requests

  Open or update a pull request with documentation changes. The app posts a comment linking to the live preview for that PR's head branch.

The app uses the same ~ref URL model as branch preview. It works on public repositories only, the same constraint as docs.page hosting. No webhook or secret configuration in docs.json is required.

For how comments tie to ref URLs and custom-domain preview links, see GitHub App.

Run docs check in GitHub Actions so broken internal links, missing assets, and other problems fail the workflow before you merge, even when contributors skip local check.

Add a job step that runs from the directory containing docs.json:

- name: Check documentation
  run: npx @docs.page/cli check

The command exits with code 1 when any error-level issue is found, which fails the job. It does not publish or upload anything, Public GitHub hosting updates the live site when you merge to your default branch.

External targets sometimes block automated requests or are temporarily unreachable in CI. Keep internal links and assets strict while relaxing externals:

- name: Check documentation
  run: npx @docs.page/cli check --external-links warn --internal-links error --assets error

Each category accepts off, warn, or error. All three default to error. See the CLI reference for the full flag list.

When review is complete and CI passes, merge your pull request into the repository's default branch (usually main).

docs.page serves production from that default branch automatically. There is no separate build, upload, or promote step. After merge, open your canonical URL (without a ~ref segment) and confirm the changes are live:

https://docs.page/{owner}/{repo}
https://docs.page/{owner}/{repo}/{page-path}

Edge caching may delay updates by about a minute after the merge. Renaming the default branch on GitHub updates what the production URL serves, you do not configure a production branch in docs.json. See Public GitHub hosting.

You do not need a local clone for small fixes. On any live or branch preview page, open the Copy page menu and choose Edit page. docs.page opens the matching docs/{path}.mdx file in GitHub's web editor on the resolved branch.

After you save on GitHub, the preview or production site updates on the next request. There is no separate publish step. See Page actions for the full header menu.