Your first sync

Work outwards: render with no network, then plan against the site, then publish.

1. Render, touching nothing

npx pterodocs render

Writes the rendered block markup for every page into .pterodocs/, along with manifest.json (what goes where), plan.json (what would happen) and docs.css. It contacts nothing and needs no credentials.

Open a file under .pterodocs/pages/ and read it. That is exactly what will be stored as the page’s content.

2. Plan against the live site

npx pterodocs sync --dry-run --env-file .env

Now it reaches the site, reads what is already there, and reports what it would change — without writing anything:

create-root 2 · create 6 · update 6 · 50 requests
Dry run: the site was not modified.

create-root is the path pages above your documentation root — /products and /products/pterodocs in this site’s case. They are created once if missing and never edited again.

3. Publish

npx pterodocs sync --env-file .env

4. Run it again

This is the check that matters:

npx pterodocs sync --env-file .env

48 unchanged · 50 requests

Everything should report unchanged. If a second run still finds differences, the rendered output and the stored output disagree about something, and every future run will rewrite every page. Report it — that is a bug, not a quirk.

Useful flags on the way

Then what

• Check the result at your root path, and check the sidebar renders.
• Install the WordPress plugin if you want the documentation to look like documentation rather than like unstyled blocks.
• Read what a re-sync overwrites before you edit anything in the WordPress editor.