Publish
Publishing and syncing
How a change in your repository becomes a live page, what triggers a rebuild, and what to do when one doesn't.
How a change in your repository becomes a live page, what triggers a rebuild, and what to do when one doesn't.
Papervine keeps your site in step with a branch of your repository. You write and push; your docs update. This page covers what actually triggers that, how long it takes, and what to check when a change doesn’t appear.
This page describes a Git-backed site. A Papervine-hosted site has no repository, so none of these triggers apply to it — see Papervine-hosted sites below.
The usual path. Pushing to the branch you connected triggers a build automatically — no action in the dashboard.
The first build runs the moment you connect a repository.
The Re-sync control on the site’s Overview forces a build from the current branch tip. Useful after changing a setting, or when a push was missed.
Publishing an edit in the browser editor writes a commit, which triggers a build like any other push.
Only the branch you connected publishes. Pushing to other branches does nothing — which is what makes it safe to draft in a branch and open a pull request against the published one.
A build reads the changed files from your repository, compiles your MDX, measures your images, and rebuilds the search index — then swaps the result in.
Two properties matter to you as an author:
Readers never see a half-updated site. A build assembles the new version completely and switches to it in one step. Nobody lands on a page that’s half old and half new.
Later builds are much faster than the first. The first sync reads everything; after that, only what changed moves. A typo fix is usually live in seconds.
The site’s Overview shows an Activity feed with builds and their status — building, live, or failed — updating on its own as the build progresses. You don’t need to refresh.
A failed build leaves the previously published version live. Your site never goes down because a new build failed; you keep serving the last good version until a build succeeds.
Work down this list — it’s ordered by how often each is the cause.
Publishing follows one branch. A commit on docs-update won’t appear on a site
connected to main.
If the build failed, the feed says so and why. If no build appeared at all, the push never reached Papervine — re-sync manually and the problem is likely the repository connection rather than your content.
A new file that isn’t listed in docs.json renders at its URL but appears in no sidebar.
See organizing your docs.
Use Re-sync on the Overview. This rebuilds from the branch tip regardless of what webhooks did or didn’t deliver.
Published pages are cached hard so they load fast. A private window confirms whether you’re looking at a stale copy of a page that did in fact update.
Automatic rebuild-on-push depends on the repository connection being fully authorized. If pushes never trigger builds but manual re-sync always works, that connection is what to look at — not your content.
Two ways to see a change before readers do:
npx papervine dev renders your folder locally with the same engine
as the hosted site; save and refresh to see a change.Deleting the file and pushing removes the page on the next build. To keep it published but
out of the way, drop it from your docs.json navigation — it stays reachable by direct link
for anyone who bookmarked it, which is usually kinder than a 404.
A site you started from scratch has no repository, so nothing on this page about pushes, branches, or re-syncing applies to it. There is exactly one way to publish: edit in Studio and hit Publish. The change is live on your site — there’s no build to wait for and no pull request to merge.
Your live site keeps serving its previous content until a publish completes, and a publish that fails leaves your draft untouched, so you can simply publish again.
To take a page down, delete it in Studio and publish.