Shopify rich text vs markdown — how Spectersync round-trips article bodies

If you’ve spent any time in Shopify’s article editor, you know it’s a rich-text box. You bold something, you make a heading, you drop in an image. Under the hood, Shopify stores all of that as HTML — not markdown, not a block tree, just a chunk of HTML in the article’s body_html field. That’s what the Admin API returns and what it expects back.

Spectersync works on clean, structured content. When you connect, each article opens in the workspace as readable prose that you and an AI recipe can edit directly. So every sync involves a conversion: HTML on the way in becomes clean editable content, and your edits become HTML on the way back out. This guide is the honest version of what survives that round trip cleanly and what doesn’t, so there’s no mystery the first time you publish.

Why project through clean content at all

A reasonable question: if Shopify stores HTML, why not just edit the HTML?

Two reasons.

Writers are faster in clean prose. Headings, lists, links — there’s nothing to format and nothing to misclick. You write the article, you don’t decorate it.

AI is faster in clean prose too. A model reading clean structured content understands the article without parsing a tag soup, produces clean output without remembering to escape attributes, and the diff between two versions is readable. Hand a model an HTML blob and it’ll work, but it’ll also drift. Give it clean content and it edits the way you’d edit it. That readable content is the lingua franca between your fingers, the AI, and the diff you review. The HTML lives in Shopify, where it belongs.

What round-trips cleanly

These survive the HTML → clean-content → HTML loop with no loss of meaning and no surprises in the Shopify article view:

Paragraphs. Plain text, normal breaks, nothing surprising.
Headings. <h1> through <h6> map cleanly both ways; heading IDs are preserved where Shopify generates them.
Bold, italic, strikethrough. Standard both ways.
Ordered and unordered lists. Nesting is preserved.
Links. Inline and the underlying <a href> round-trip with their target and rel attributes intact.
Blockquotes. Single-level and nested.
Code blocks and inline code. Fenced code round-trips with its language hint.
Images by URL. Image syntax round-trips with the alt text and source URL preserved. Spectersync does not re-upload images on every sync — the URL stays the URL.
Tables. Round-trip through standard table syntax.

If your articles are mostly prose, lists, headings, links, and the occasional image — i.e., what a normal blog article actually is — you’ll never notice the conversion is happening.

What’s lossy (and what we do about it)

Some things in Shopify’s rich-text editor don’t have a clean editable equivalent. Rather than silently dropping them or guessing, Spectersync preserves them as opaque HTML blocks. They’re clearly marked, they round-trip back to Shopify exactly as they came, and you can leave them alone or rewrite the prose around them.

The main offenders:

Embedded Shopify product cards in articles. If you’ve used the editor’s “insert product” widget, the result is a Shopify-specific block with no clean analogue. Spectersync preserves it verbatim so it renders correctly on publish.
Embedded video/iframe blocks. YouTube, Vimeo, generic <iframe> tags. Kept as raw HTML.
Custom HTML pasted into the editor’s “Show HTML” view. Treated as opaque and round-tripped exactly.
Inline styles and class attributes. Shopify’s editor sometimes attaches style="" or class names. Spectersync preserves them so your theme CSS keeps working.

“Opaque” here means readable and editable. You can see the HTML, you can ask a recipe to rewrite the surrounding paragraphs without touching the block, and you can delete the block entirely. What Spectersync won’t do is silently convert a Shopify-specific block into a <p> and hope you don’t notice. When this matters for a run, the diff flags it rather than letting you discover it later.

What this means for AI editing

The practical version of all of the above:

For prose work, the clean content is the right surface. When you edit articles with AI recipes, the model reads and writes exactly what you’d write by hand. The conversion happens at the sync layer, not in the editor.

For SEO work, the metadata is its own surface. Title, handle, SEO title, SEO description, tags, summary — all exposed separately from the article body. That’s why a bulk SEO pass is so easy: the AI doesn’t have to parse the body to update a meta description.

For articles with embedded product cards, give the recipe clear instructions. “Rewrite the prose around the embedded HTML blocks but leave the blocks themselves untouched.” Every model worth its tokens will follow that.

When the round-trip might surprise you

A few honest edge cases:

You edited the same article in the Shopify admin and via a recipe. Spectersync’s conflict prompt catches this — you choose which version wins. The conversion isn’t to blame; the divergence is.
You hand-edited an opaque HTML block into broken markup. The next publish sends broken HTML to Shopify, which renders it as best it can. Treat the opaque blocks like the HTML they are.
You pasted Word-formatted content into the Shopify editor before Spectersync ever touched the article. Word HTML is famously dirty. The first sync normalises the worst of it, but a few stray <span> tags may survive.

None of this is a deal-breaker; it’s the price of HTML being the storage format on the Shopify side. For the 95% of your article body that’s prose, the conversion is invisible.

The mental model

Shopify stores HTML because Shopify is a CMS. You and your AI work on clean content because that’s the format both of you actually want. Spectersync converts between the two on every sync, preserves the things that don’t have a clean equivalent as opaque blocks, and gets out of the way. Your article looks the same in the Shopify admin after the round trip as it did before — that’s the test, and that’s the bar. Subscribe now →

Running the engine on your own machine?

The same conversion runs in the desktop and open-source edition, where each article body lands as a .md file on your Mac and the opaque blocks sit inline in the markdown for your own AI or scripts to work around. That guide covers the local file specifics.