skills/sanity-io__agent-toolkit
1
0
Fork 0
mirror of https://github.com/sanity-io/agent-toolkit.git synced 2026-09-14 18:39:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

sanity-migration: address Webflow reference review — package name + API notation

Browse Source 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwCiGS4nB5F1Benh3jYTun
This commit is contained in:
Claude
2026-07-28 19:25:36 +00:00
parent c2dc31666b
commit ec425fe90f
1 changed files with 4 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/sanity-migration/references/webflow.md
+4 -4
View File
@@ -24,10 +24,10 @@ Before writing migration code, determine:
Use different extraction paths for CMS content and static pages:
- **CMS collections (Data API, preferred):** `GET /v2/collections/{id}/items`, paginate at `limit=100` with an offset, and stream to NDJSON (one item per line) so large collections never accumulate in memory. Reference fields come back as Webflow item ID strings — single-ref is one string, multi-ref an array — which gives clean ID-to-ID joins. Back off on `429` using the `retry-after` header.
- **CMS collections (Data API, preferred):** `GET /v2/collections/{collectionId}/items`, paginate at `limit=100` with an offset, and stream to NDJSON (one item per line) so large collections never accumulate in memory. Reference fields come back as Webflow item ID strings — single-ref is one string, multi-ref an array — which gives clean ID-to-ID joins. Back off on `429` using the `retry-after` header.
- **CMS collections (CSV, fallback):** export each collection as CSV when API access is unavailable. Audit and normalize before import.
- **Site structure via API:** `GET /sites/{id}/collections` (field types, reference targets), `/pages` (slugs + SEO metadata — this is your URL inventory, no sitemap XML needed), `/components` (component definitions), `/forms` (field schemas), and `/custom_code` (script inventory; Business plan or higher). Save each response as JSON and inspect before modeling.
- **Static pages (DOM API):** `GET /v2/pages/{page_id}/dom` returns only editable content nodes — `text`, `image`, and `component-instance` (each with a `propertyOverrides` array of the content set per instance). It carries no layout context; pair it with the HTML export, which is the only source of section structure.
- **Site structure via API:** `GET /v2/sites/{siteId}/collections` (field types, reference targets), `/v2/sites/{siteId}/pages` (slugs + SEO metadata — this is your URL inventory, no sitemap XML needed), `/v2/sites/{siteId}/components` (component definitions), `/v2/sites/{siteId}/forms` (field schemas), and `/v2/sites/{siteId}/custom_code` (script inventory; Business plan or higher). Save each response as JSON and inspect before modeling.
- **Static pages (DOM API):** `GET /v2/pages/{pageId}/dom` returns only editable content nodes — `text`, `image`, and `component-instance` (each with a `propertyOverrides` array of the content set per instance). It carries no layout context; pair it with the HTML export, which is the only source of section structure.
- **Static pages (HTML export):** requires a paid Webflow plan. Analyze page sections separately from CMS collection data.
- **Components:** inventory components in the Webflow Designer (name, variants, pages used, reusable content vs. layout-only vs. one-off) before relying on HTML export — exported HTML does not preserve component intent. The Components API (`components.json`) lists definitions but not that editorial judgment.
- **Assets:** the Webflow Assets API only returns the Site Assets panel — it misses CMS-field and rich-text images. Instead scan for asset URLs across NDJSON field data, rich-text HTML, static-page HTML, CSS, and Open Graph metadata, plus local `images/` paths in the HTML export.
@@ -59,7 +59,7 @@ Webflow CMS constraints create anti-patterns worth fixing on the way in, not cop
- Prefer the Data API's item-ID references over slug/name joins; build a Webflow item ID → Sanity ID lookup (`id-map.json`) before resolving references.
- Use deterministic Sanity IDs of the form `<typeName>-<webflowItemId>` (e.g. `blog-664a0fba...`) so a document's type is readable from its ID and reruns stay idempotent.
- Normalize values before import: empty columns, inconsistent taxonomy spellings, boolean-like strings, and duplicate slugs (especially in CSV exports).
- Convert rich text with `htmlToBlocks()` from `@sanity/block-tools`, adding custom deserializer rules for your export's image and embed patterns. Decide how each HTML pattern maps to a block type before writing code.
- Convert rich text with `htmlToBlocks()` from `@portabletext/block-tools`, adding custom deserializer rules for your export's image and embed patterns. Decide how each HTML pattern maps to a block type before writing code.
- Upload assets before document import, then reference the uploaded assets and replace Webflow CDN URLs in rich text and image/file fields. Upload SVGs and other non-raster files as `file`, not `image`.
- For static pages, identify section patterns first, then design Sanity objects. Ask what fields editors need to manage, not what CSS classes exist.
- Use variant fields only when variants are editorially meaningful and stable, such as `tone`, `emphasis`, or `layoutIntent`.