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.
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, with live reload.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.