Skip to content

Self-contained sync rules and sync streams sections - #655

Open
benitav wants to merge 11 commits into
sync-streams-navfrom
sync-rules-deprecation
Open

benitav wants to merge 11 commits into
sync-streams-navfrom
sync-rules-deprecation

Conversation

@benitav

@benitav benitav commented Sep 18, 2026

Copy link
Copy Markdown
Collaborator

Stacked on #640, merge that one first.

This PR mostly contains structural/navigational updates so that the Sync Streams and Sync Rules docs are more self-contained. I also fixed some existing inconsistencies and polished things along the way. The below summary was generated by Claude:

Sync Rules are deprecated, so this PR separates the two engines in the docs. The Sync Streams section reads as if Sync Rules never existed, and the Sync Rules (Legacy) section has everything a Sync Rules user still needs while they migrate.

Split pages: pages that covered both engines are now one Sync Streams page and one Sync Rules page under sync/rules/.

  • Supported SQL, Prioritized Sync, Sync Data by Time, Multiple Client Versions, Partitioned Tables.
  • Storage Version 4 gets a short Sync Rules summary that links to the Sync Streams page for details, since incremental reprocessing requires Sync Streams.
  • The Grammar Reference already had a page per engine. The Sync Rules one moves into the new Reference group.

Shared pages: pages that apply to both engines keep one body in snippets/sync-shared/, with engine-neutral wording, rendered by a wrapper page in each section.

  • Type Mapping, Client ID, Case Sensitivity, Schemas and Connections, Sharded Databases.
  • Each wrapper has its own URL, so the sidebar highlights the right section, and no content is duplicated.

Sync Streams only: these Advanced topics are newer guides and functionality written for Sync Streams, so they get no Sync Rules version.

  • Compatibility.
  • Reducing Bucket Count.
  • The Advanced overview page that links to them.

Counterpart comments: every split page, wrapper, and shared snippet starts with an MDX comment naming its counterpart, so future edits consider both sides.

Sync Rules pages:

  • Every page under sync/rules/ opens with a deprecation callout, except the migration guide itself. Split pages link to their Sync Streams version, concept pages to the closest Sync Streams equivalent, and shared pages state that they apply to both engines.
  • The Sync Rules overview says plainly that Sync Rules are deprecated and how to migrate. The link to the announcement follows once it is published; TODO comments mark the spots.
  • The sidebar group gets Reference and Advanced sub-groups, mirroring the Sync Streams section. The redirect from /sync/rules/supported-sql is removed because that page exists again.

Sync Streams pages: no longer mention Sync Rules, with one exception. Storage Version 4 states that incremental reprocessing is not supported for Sync Rules.

Tooling:

  • pnpm check:links now runs scripts/check-links.mjs, which wraps the Mintlify checks and resolves anchors defined in imported snippets. CI runs the same command.
  • The agent instructions in .claude/ are updated: new docs cover Sync Streams, Sync Rules docs stay accurate without being prioritized, and the two engines are never shown side by side.

Worth a look on the preview: the shared pages in both sections (the Type Mapping pages import a nested snippet), and sidebar highlighting on those pages.

🤖 The updates were made by Claude Code, and it also generated the above summary. I had Claude review all changes in the PR multiple times against the review harness, and made it verify accuracy against the source code. I manually checked the structure and reviewed files on a high level (since these were mostly structural changes).

@benitav
benitav added this pull request to stack #656 September 18, 2026 16:18
Comment thread snippets/sync-shared/case-sensitivity.mdx Outdated
Comment thread snippets/sync-shared/client-id.mdx Outdated
Comment thread snippets/sync-shared/sharded-databases.mdx Outdated
Comment thread snippets/sync-shared/schemas-and-connections.mdx Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant