Before you begin
- Install the CLI or use
npx @docs.page/cli - Page files or
docs.jsonedits ready to review, see Write if you still need to create content
Run commands from the directory that contains docs.json. For more in-depth configuration, see CLI.
This page covers two local tasks before you continue to Publish:
- Preview: open your docs in the browser and watch edits reload as you save files
- Check: scan the project for broken links, missing assets, and invalid frontmatter targets
Preview while you edit so you can judge layout, navigation, and components. Run check when you want an automated pass over the whole site, it catches problems preview will not surface, such as a typo in a link on another page.
Start from the folder that contains docs.json
Open a terminal at your project root (the directory with
docs.json).See your docs in the browser
bashnpx @docs.page/cli previewThe CLI watches
docs.json(ordocs.yaml) anddocs/**/*.mdx, starts a WebSocket server onlocalhost, and opens your browser to a URL shaped like:texthttps://docs.page/preview?url=ws://localhost:57250The browser loads the production preview shell while file reads and bundling stay on your machine. Save a file under
docs/or updatedocs.jsonand the page reloads within a few seconds.Override port or skip auto-open when needed
bashnpx @docs.page/cli preview --port 4000 npx @docs.page/cli preview --no-browserUse
--portwhen the default port is taken or you need a fixed number. Use--no-browserin remote development or when you want to copy the printed Preview URL manually.Stop the preview server when finished
Press
Ctrl+Cin the terminal when you are done.
Local preview does not include Search, sitemap generation (Search engine indexing), or the in-docs Ask AI panel. Those features require a published site. See Local preview for how the preview shell works and known limitations.
Catch link and asset problems automatically
bashnpx @docs.page/cli checkBy default, all categories report at error severity. The CLI validates internal links (paths to pages or assets in the repo), assets (images and files on disk), external links (reachable URLs), and frontmatter paths (
redirect,next, andprevioustargets).Fix every reported issue before you push
Resolve typos in paths, missing files under
docs/, broken external URLs, or invalid frontmatter targets. Re-run check after each fix. A clean run prints noerror-level issues and exits with code0.Tune severity when external checks are noisy
bashnpx @docs.page/cli check --external-links warn --internal-links error --assets errorEach of
--external-links,--internal-links, and--assetsacceptsoff,warn, orerror. See CLI: check for defaults and exit codes.
When preview looks right and check exits with code 0, continue to Publish to share your changes on GitHub.
| Symptom | Likely cause | Fix |
|---|---|---|
| CLI exits before preview starts | Missing docs.json, no docs/ directory, or no .mdx files | Add the required files or run init |
| Browser shows a connection error | Preview server stopped or you opened an old URL | Restart preview and open the newly printed Preview URL |
| Port already in use | Another process bound the 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 reports a broken internal link | Path typo, wrong root-relative path, or file not yet added | Use paths like /authoring/preview, no domain and no .mdx extension. See Write: Links and assets |
Check fails on redirect, next, or previous | Frontmatter target does not match a real page path | Fix the path or add the missing page. See Page frontmatter |
| External link failures | Target blocks automated requests or is temporarily down | Fix the URL, or set --external-links warn or off for that run |
| Check passes locally but fails elsewhere | A different working directory was checked | Pass the correct [path] argument or run from the project root that contains docs.json |
For more detail on both commands, see CLI.