When someone opens https://docs.page/acme/handbook, the HTML they see is not a static export sitting on a CDN bucket. docs.page fetches your public GitHub repository, bundles the matching MDX page, and returns a rendered site from the files you committed.
GitHub is the source of truth for a hosted docs.page site. Configuration lives in docs.json (or docs.yaml) at the repository root; page content lives under docs/**/*.mdx. docs.page does not clone your repo into a dashboard or run a separate deploy pipeline. It fetches those files from GitHub and renders them at request time.
That model is push-to-publish: merge or push to your default branch and the live site reflects those commits. There is no build artifact to upload and no hosting project to configure beyond making the repository public and adding the required files.
See Introduction for the file layout and how paths under docs/ map to URL segments.
URLs without a ref segment serve content from the repository's default branch (usually main, but whatever GitHub reports as the default for that repo).
https://docs.page/{owner}/{repo}
https://docs.page/{owner}/{repo}/{page-path}For example, https://github.com/acme/handbook with default branch main is served at https://docs.page/acme/handbook. A page at docs/usage.mdx is https://docs.page/acme/handbook/usage.
docs.page resolves the default branch through the GitHub API on each bundle request. You do not configure a production branch name in docs.json. Renaming the default branch on GitHub updates what the canonical URL serves. There is no separate promote-to-production step.
On each page request, docs.page:
- Parses the URL into owner, repository, optional ref, and page path
- Fetches
docs.json(ordocs.yaml) and the target.mdxfile from GitHub at the resolved ref - Validates configuration, bundles MDX, and returns the rendered page
Responses are cached at the edge for a short period (on the order of one minute), so a push may take a moment to appear everywhere. There is no manual "publish" button. Visibility follows Git.
docs.page only hosts public GitHub repositories. If the repository is private, the platform returns a 403 error before any content is bundled or served.
Keep documentation in a public repository, or in a dedicated public docs repo linked from your project. docs.page cannot serve private repos, even with a GitHub token on your side.
If you need access-controlled documentation, use a self-hosted static generator or a custom app with your own auth layer.
To serve a branch, commit, or pull request before it merges, add a ~ref segment after the repository name. Production URLs omit this segment entirely.
https://docs.page/{owner}/{repo}~{ref}
https://docs.page/{owner}/{repo}~{ref}/{page-path}See Branch preview for ref URL patterns, when to use shareable previews, and how the GitHub App adds PR comments.
For iterating on your machine before you push, use Local preview instead.
Every rendered doc page includes a Copy page control in the header: a primary button plus a dropdown menu. Readers and contributors use it without configuration in docs.json.
| Menu item | What it does |
|---|---|
| Copy page | Copies the current page as rendered markdown to the clipboard |
| Edit page | Opens the source .mdx file on GitHub in the web editor (default branch or current preview ref) |
| View markdown | Opens the current page at {path}.md for raw source from GitHub in the browser |
| Install with MCP | Opens the Install MCP dialog with endpoint URL and client config snippets |
| Open in Claude | Opens Claude on the web with a prompt to read the current page URL |
| Connect to VSCode | Deep link to register this site's MCP server in VS Code |
| Connect to Cursor | Deep link to register this site's MCP server in Cursor |
Edit page is disabled during local preview. Install with MCP, Connect to VSCode, and Connect to Cursor require a public site with MCP enabled. When mcp.enabled is false, the MCP endpoint is unavailable but the menu items may still appear.
Several shortcuts also appear in the ⌘K command palette when the input is empty: Ask AI (when enabled), Install MCP (when MCP is enabled), and GitHub. See Search.
Contributors fixing typos without a local clone can use Edit page from any live or branch preview URL. See Publish. For agent setup from the menu, see MCP server.