Sync Cbl Docs

Sync Couchbase Lite Docs

Sync a page in the Couchbase Lite for Dart documentation site with the official Couchbase Lite documentation from https://github.com/couchbase/docs-couchbase-lite.

Overview

The Dart docs at docs/docs/*.mdx mirror topics from the official Couchbase Lite docs. The official docs are written in AsciiDoc for Antora and use the Swift module as the primary reference implementation. This skill fetches the official page, compares it to the Dart version, and rewrites the Dart page to incorporate new or changed content — adapted for Dart APIs, MDX format, and the project's custom components.

Workflow

Step 1: Identify the page mapping

Use the page mapping in references/page-mapping.md to find which official doc file corresponds to the user's request. If the user gives you a Dart page name (e.g., "databases"), look up the corresponding official file path. If they give you an official page name, find the Dart counterpart.

After resolving the mapping, verify that the mapped Dart MDX file actually exists in docs/docs/. If the mapping is stale, find the current file in the repo and update references/page-mapping.md as part of the task.

Never derive the official AsciiDoc filename from the Dart page name or title. Always use the mapping file for the upstream page name.

Step 2: Fetch the official page

Use curl (via Bash) to fetch the raw AsciiDoc source from GitHub. Do not use WebFetch — it summarizes AsciiDoc content instead of returning the raw source, which causes sections to be lost.

curl -sL "https://raw.githubusercontent.com/couchbase/docs-couchbase-lite/release/4.0/modules/swift/pages/{filename}.adoc"

The official docs use AsciiDoc with Antora conventions:

• = Title for H1, == Section for H2, etc.
• include:: directives pull in code snippets from example files — see below for how to fetch them
• xref:swift:page.adoc[Label] for cross-references
• Admonitions: NOTE:, TIP:, CAUTION:, IMPORTANT:
• Code blocks: [source, swift] followed by ---- delimited blocks
• Tags in code: tag::name[] / end::name[] delimit named regions

Fetching included code snippets

The AsciiDoc pages use include:: directives to pull in Swift code examples. These are available on GitHub and should be fetched so you can see the actual Swift code being shown in the official docs.

Include paths follow the Antora convention module:example$path. For example:

include::swift:example$code_snippets/SampleCodeTest.swift[tags="fts-index"]

maps to:

curl -sL "https://raw.githubusercontent.com/couchbase/docs-couchbase-lite/release/4.0/modules/swift/examples/code_snippets/SampleCodeTest.swift"

The [tags="name"] attribute selects the region between // tag::name[] and // end::name[] markers in the source file. Use grep to extract the relevant tagged regions after fetching the file.

Seeing the original Swift code helps you write accurate Dart equivalents — you can see the exact API calls, parameter names, and patterns used.

Step 3: Read the current Dart page and build a section map

Read the existing MDX file from docs/docs/.

Before writing anything, build a section-by-section comparison between the official page and the Dart page. List every section heading from the official page and note whether it exists in the Dart page, is missing, or has different content. This prevents accidentally dropping sections during the rewrite.

The Dart page may be a stub (just a placeholder pointing to the Swift docs) or a full page with existing content. For stubs, you're writing the page from scratch based on the official docs. For full pages, you're doing a differential update. Either way, the section map ensures completeness.

Step 4: Check available Dart APIs and behavior

Before writing code examples or referencing APIs, verify they exist in the Dart codebase. The public API lives in packages/cbl/lib/src/. Key locations:

• Database API: packages/cbl/lib/src/database/
• Document API: packages/cbl/lib/src/document/
• Query API: packages/cbl/lib/src/query/
• Replicator: packages/cbl/lib/src/replication/
• Blobs: packages/cbl/lib/src/document/blob.dart
• Logging: packages/cbl/lib/src/log/

Use Grep/Glob to find the actual class names, method signatures, and enum values. The Dart API doesn't always have a 1:1 correspondence with Swift — for example, Dart has separate openAsync/openSync methods where Swift has a single initializer.

Differences between the Dart SDK behavior should be verified with runtime checks while implementing or updating docs. If a Dart-specific behavior could reasonably differ from the upstream documentation, verify it with an existing test or a focused runtime check before documenting it as fact.