Webflow CMS vs. local markdown — what round-trips, what doesn't

Desktop & open-source edition. Prefer to work in your browser? Open this in the Spectersync webapp → — subscribe now for 500 free credits when your workspace opens.

Specter’s job is to keep your Webflow CMS and a folder of markdown files perfectly in sync. That works because most of the Webflow CMS maps cleanly to markdown — but not all of it. This guide is the honest map of what round-trips losslessly, what round-trips with a known projection, and where Specter intentionally treats something as opaque so you don’t lose data on a push.

If you’re about to run a bulk edit and want to know what’s safe to touch and what to leave alone, this is the page.

How Specter represents an item

One CMS item is one .md file. The frontmatter at the top of the file holds the structured fields — anything that isn’t the rich-text body. The body of the file is the item’s rich-text body, converted to markdown.

---
collection: blog
itemId: 6512a0...
slug: launching-specter-for-webflow
name: "Launching Specter for Webflow"
draft: false
archived: false
publishedOn: 2026-05-28T11:17:37+02:00
author: 6471f3...           # reference field (item id)
tags: [launch, webflow]      # multi-reference field (item ids)
featuredImage: https://...   # image field (URL)
seoTitle: "Launching Specter for Webflow — CMS sync without the Designer"
seoMetaDescription: "..."
ogImage: https://...
---

# Launching Specter for Webflow

The rich-text body lives down here as standard markdown.

The frontmatter keys mirror the field slugs in your collection — if you renamed a field in Webflow, the corresponding frontmatter key changes on the next pull.

What round-trips losslessly

These field types pull and push without information loss:

Plain text — name, summary, short text fields.
Slug — the item slug as the slug frontmatter key.
Switch (boolean) — draft, archived, and any custom switch fields.
Number — integers and decimals round-trip as JSON numbers in frontmatter.
Date / DateTime — ISO-8601 strings in frontmatter.
Link — URL strings.
Color — hex strings.
Option — the option name as a string.
Reference — the referenced item’s id as a string. Multi-reference fields become an array of ids.

For these field types, “what you see in the Editor” and “what’s in the markdown frontmatter” are equivalent. Bulk-editing them is safe.

What round-trips as a known projection

These field types are richer than markdown frontmatter, so Specter uses a defined projection in both directions:

Rich text — converted to markdown on pull, converted back to Webflow rich text on push. Headings, paragraphs, lists, bold, italic, links, code blocks, inline code, blockquotes, and images all round-trip cleanly. Tables round-trip as standard markdown tables. The conversion is deterministic, so editing the markdown and pushing back will not produce a different rich-text body than the one you started with.
Image — Specter stores the image URL in frontmatter (featuredImage: https://...). Uploading a new local image file from disk isn’t supported yet; you can swap the URL to one you’ve already uploaded to Webflow’s asset hosting.
File — same as image: stored by URL, swapped by URL.

For these, “what you see in the Editor” and “what’s in the markdown” are equivalent for the cases the projection covers. If your rich-text body uses a feature outside the projection (see the next section), Specter falls back to opaque handling rather than losing data.

What’s treated as opaque (safe by default)

These cases can’t be cleanly represented in markdown, so Specter doesn’t try — it preserves them verbatim and round-trips them as opaque blocks so you don’t lose data on a push:

Embedded components inside rich text. Webflow lets you drop a component instance into a rich-text body. The component’s data is held as an opaque JSON block in the markdown. You can leave it alone, delete it, or replace it; you can’t edit the component’s internals from markdown — that’s a Designer-side job.
Custom HTML blocks inside rich text. Same shape — preserved verbatim as a fenced block in the markdown.
Custom code (head, body, footer) attached to an item — preserved verbatim in frontmatter under a customCode key.

These are the “if you touch them, you do it on purpose” parts. A bulk find-and-replace over text bodies won’t accidentally rewrite an embedded component, because the component lives in a fenced block.

What’s not in scope at all

Some Webflow concepts aren’t fields on a CMS item, so Specter doesn’t represent them:

The Designer — page structure, layouts, components, interactions, custom code at the site level. Out of scope. The Designer remains the Designer’s job.
Site SEO outside what each collection exposes — Specter syncs the per-item SEO fields the collection defines, not site-level meta.
Forms — submissions and form definitions are out of scope.
Memberships — membership records and access rules are out of scope.
Webflow Ecommerce — products, variants, orders, customers, inventory are out of scope.

If you need to touch any of those, you’re back in Webflow.

Pre-bulk-edit checklist

Before you run a bulk edit on a Webflow collection, the three things to check:

Are the fields you’re editing in the “lossless” or “projection” categories? If yes, the bulk edit is safe. If you’re targeting an opaque block (an embedded component), don’t — handle those one at a time in the Designer.
Are you preserving the itemId field in frontmatter? That’s how Specter knows this markdown file maps to this CMS item. If you delete it, Specter will treat the file as a new item to create rather than an existing one to update.
Is Preview Sync showing the diffs you expected? If the diff is larger than you thought (touched fields you didn’t mean to touch), revert locally and re-prompt — don’t push. The whole point of the preview step is to catch the surprise.

The pattern that holds: lossless fields and the projection cases are great for bulk. Opaque blocks and Designer-side concerns are not.