content.soubiran.dev

content.soubiran.dev is a Cloudflare Worker that accepts complete Markdown snapshots and reconciles them with an existing Cloudflare AI Search instance.

Each Markdown file becomes one page item plus one item for every h2 and h3 section. The service owns the target instance’s built-in items and removes items that are no longer present in the submitted snapshot.

Every Markdown file must declare a non-empty string id in its YAML frontmatter:

---
id: getting-started
---
# Getting started

The page item and all section items derived from the file share this ID in their AI Search metadata. Files without a valid ID are rejected during asynchronous validation.

How synchronization works

1. A client submits a complete snapshot to POST /v1/sync.
2. The Worker streams the request into R2 and places only a small job reference on a Cloudflare Queue.
3. The consumer validates and normalizes the snapshot, then materializes page and section items.
4. A Durable Object serializes work per AI Search instance and keeps only the newest pending snapshot.
5. The reconciler uploads new or changed built-in items and deletes stale built-in items.

The endpoint returns 202 Accepted once the snapshot is durably staged and queued. This does not mean that validation or AI Search indexing has finished. There is intentionally no job-status endpoint; use structured Worker logs and the Queue dead-letter queue for operations.