Source material evolves: code lands, OpenAPI specs change, websites get re-published, files get edited. Re-sync is how you bring a generated section back in step with its sources without losing the manual edits you've made along the way. Every re-sync is staged as pending proposals you review before anything touches your live content.
Why re-sync is review-based
When GitDocAI first generates a section, it writes the content end-to-end. After that, you typically edit pages by hand: better wording, extra examples, missing context. A naive re-generation would overwrite all of that.
Re-sync solves it by running an evolve pipeline: GitDocAI re-reads the sources, compares the new draft against your current content, and produces a structured diff — new pages, modified pages, removed pages — instead of overwriting. You see exactly what's changing and choose what to accept.
flowchart TD
A[Sources drift upstream] --> B[Stale indicators appear]
B --> C[You trigger re-sync]
C --> D[Evolve pipeline runs]
D --> E[Proposals staged]
E --> F{Review each one}
F -- Accept --> G[Merged into draft]
F -- Reject --> H[Discarded]
G --> I[Publish when ready]Detecting drift
GitDocAI continuously polls connected sources for changes and flags drift in two places:
Inside the editor, the Source sidebar shows stale indicators next to any resource whose upstream content has changed since the last generation.
At the documentation level, a banner appears when one or more sections have unreviewed pending changes, with a shortcut to jump straight into review.
What counts as drift depends on the source type:
| Source | Drift signal |
|---|---|
| GitHub repository | New commits on the tracked branch since the last sync. |
| Website | Content hash changes detected on the next crawl. |
| OpenAPI spec (uploaded) | A new version of the spec uploaded into the section. |
| OpenAPI spec (repo file) | New commits affecting the spec file path. |
| Files | Files re-uploaded with different content. |
Triggering a re-sync
- 1
Open the section
Click the section tab whose sources have drifted.
- 2
Open the Source sidebar
Stale resources are flagged. You can adjust the source set first (add or remove files) — the re-sync will incorporate those changes too.
- 3
Click Re-sync
GitDocAI runs the evolve pipeline. Progress streams in real time, just like the initial generation.
- 4
Review proposals
When the pipeline completes, the editor enters review mode with the pending-changes banner visible.
Reviewing proposals
There are three proposal kinds, each with its own review UI:
Updated pages
Pages whose content changed get a side-by-side diff — your current version on one side, the proposed version on the other. The split-pane editor lets you scan everything in context. Accept to overwrite, reject to keep your current page intact.
New pages
Pages added by the re-sync are rendered in full inside the rich-text reviewer with an Accept/Reject bar at the top. Accepting inserts the page into the sidebar at the position the pipeline suggested; you can reorder it afterward.
Deleted pages
Pages whose source material is gone get marked for deletion. The current page is shown with a delete confirmation — you have to explicitly confirm before it's removed.
Proposals are reviewed independently. You can accept some and reject others. The section stays in review mode until every proposal has a decision, at which point the pending-changes banner clears and the Publish button re-enables.
OpenAPI spec diff
Re-syncing an API Reference section uses a dedicated spec-diff renderer instead of the generic page-diff. You see:
Endpoints added, removed, or modified, grouped by tag.
Per-endpoint changes: method/path moves, parameter additions and removals, response schema changes.
A summary line counting the totals so you can gauge the scope at a glance.
Accept changes endpoint-by-endpoint — useful when a single OpenAPI publish covers multiple unrelated areas.
Publish gating
While any proposal is pending, the Publish button is disabled for that documentation. This is intentional: it prevents a half-reviewed re-sync from leaking to readers. Accept or reject every proposal, then publish.
If a re-sync produces a lot of noise (formatting-only changes, for example), you can reject everything at once with the Reject all action and trigger a fresh re-sync after improving the source. Nothing is committed until you accept.
Related
Importing Content Sources — adding and removing sources, which feeds re-sync.
Using the Content Editor — the proposal review UI is shared with in-editor AI edits.
Documenting APIs and Workflows — the OpenAPI flow that uses the spec-diff renderer.