Run docs preview when you want to see layout and theme changes before pushing to GitHub. The CLI watches docs.json (or docs.yaml) and docs/**/*.mdx on your machine, renders each page with the same production content pipeline, and streams updates to the hosted preview UI.
For the full command workflow (flags, troubleshooting, and CI integration), see Preview locally on the CLI page.
- A docs.page project with
docs.json(ordocs.yaml) and at least one.mdxfile underdocs/ - Install the CLI or use
npx @docs.page/cli
For shareable branch and pull request previews after you push, see Branch preview.
Open a terminal at your project root
Use the directory that contains
docs.json.Start the preview server
bashnpx @docs.page/cli previewThe CLI starts a local WebSocket server, prints the socket URL, and opens your browser to a preview URL shaped like:
texthttps://docs.page/preview?url=ws://localhost:57250The browser loads the production preview shell while file reads and bundling stay on localhost.
Edit and save
Change any watched file under
docs/or updatedocs.json. The preview reloads without a Git push.Customize port or browser behavior when needed
bashnpx @docs.page/cli preview --port 4000 npx @docs.page/cli preview --no-browserUse
--no-browserin remote development or when you want to copy the printed URL manually.
After the server starts, confirm:
- The terminal shows
Local preview server startedand a Preview URL - The browser renders your home page with the correct project name and sidebar
- Saving a visible change in
docs/index.mdxupdates the preview within a few seconds
Local preview does not include search, sitemap generation, or the in-docs agent panel. Those features require a published site or branch preview. Run docs check after preview looks right and before you push.
Local asset resolution in preview mode has known gaps. Prefer relative paths that match how files are laid out in your repository.
| Symptom | Likely cause | Fix |
|---|---|---|
| CLI exits before the server starts | Missing docs.json or no .mdx under docs/ | Run init or add the required files |
| Browser shows a connection error | Preview server stopped or wrong URL | Restart docs preview and open the newly printed URL |
| Port already in use | Another process bound the default port | Pass --port with a free port number |
| Preview looks stale | Editor did not save the file | Save the file; confirm the terminal still shows the watcher running |
- Check documentation: catch broken links and missing assets before you push
- Branch preview: preview branches and pull requests on docs.page
- CLI: all commands and workflows