Saving and publishing are two different things.
Save records your work as a pending change. Nothing reaches your Git repository and nothing on your live site moves. You can leave the page, come back, and the pending version is what you see.
Publish commits every pending change on the branch, pushes it, and the
same sync pipeline that handles a git push from your terminal takes it from
there. Repo first, always — the file in Git remains the source of truth, and
publishing is how the editor writes to it.
The Publish button appears only when something is pending, and it carries
the count: Publish 3 means three pages are about to go live.
Creating a page, deleting one, renaming one and duplicating one are all pending changes too — the count covers everything about your content that has not gone live.
Pending changes are shared with your team, not private to your browser. A teammate opening the same project sees them, and either of you can publish them.
Navigation and configuration are the exception. Reordering the sidebar,
adding a group, or changing a setting in the Configurations panel commits
straight away. nookdocs.config.json is one shared file rather than one file
per page, so staging it would mean two people's edits overwriting each other
at publish time. Content is staged; structure is live.
What Publish actually does
Each pending change becomes a commit
The page's MDX — or nookdocs.config.json, if you changed it from the
Configurations panel — is committed to the repository the project syncs
from. On a managed repo the commit lands in
nookdocs-projects/<your-slug>; on a self-hosted repo
it is written through the NookDocs GitHub App installation, so it shows up
in your history like any other commit.
A pending change is cleared only after its own commit lands. If one file fails, the rest stay pending rather than being lost, and the editor names the ones that did not go through.
The push event comes back to us
GitHub notifies NookDocs about the new commit — the same webhook that fires when anyone on your team pushes from a terminal. The editor does not write to the database directly; it waits for its own commit to round-trip.
Sync runs, the site updates
The sync pipeline re-reads the changed files and updates the live site. For a single page this is typically a few seconds; you can watch it land under Deployments.
Because Publish makes real commits, everything Git gives you applies: each
change has an author and a timestamp, it shows in git log and git blame,
and reverting it is git revert — from your terminal or from GitHub's UI.
Where the file goes
The editor writes the page to its path under your content root. A page served
at /guides/webhooks becomes guides/webhooks.mdx at the repo root by
default, or under the folder named by contentRoot
when your config sets one. Monorepo base paths are honored the same way.
Protected branches
Publishing targets the branch your project syncs from, and pending changes are tracked per branch — work saved on one branch does not appear on another.
If that branch has protection rules that block direct pushes (required pull requests, required status checks), GitHub rejects the commit and the editor surfaces the error — NookDocs does not bypass protection and does not open a pull request on your behalf.
Two ways to work with protection:
Sync from an unprotected branch — point the project at a
docsbranch without required reviews and protectmainas strictly as you like.Allow the app to push — GitHub branch protection can grant specific apps bypass permission if your team prefers reviews for humans only.