How Specter handles the WordPress Block Editor (Gutenberg)

If you’re going to edit WordPress posts as markdown files on your Mac, the obvious question is what happens to the blocks. The Block Editor stores posts as a structured tree of Gutenberg blocks — each one a small chunk of HTML with a <!-- wp:block-name --> comment around it. Markdown is plain text. Something has to give in the conversion, and how much you give up depends on what your posts are built out of.

This guide is the honest answer to that question — what round-trips cleanly, what doesn’t, and what it means for the way you should actually edit. If you hit a specific conversion problem, the WordPress troubleshooting index page in help collects the common ones with workarounds.

What round-trips cleanly

For a normal post written in the standard Gutenberg editor — the blocks that ship with WordPress and the ones every theme renders without a plugin — the conversion is clean. These are the workhorse blocks, the ones most posts are made of:

• Paragraph. Plain text in, plain text out. No drama.
• Heading. ## Heading becomes an H2 block, and vice versa.
• List (ordered and unordered). Markdown lists round-trip to Gutenberg lists.
• Quote. > blockquote lines become a quote block.
• Code. Triple-backtick fenced code becomes a code block, language hint preserved when possible.
• Image (by URL). Images that point at a URL — typically the WordPress media library — round-trip as a markdown image. The URL is preserved.
• Link. Standard [text](url) syntax.
• Bold and italic. Standard markdown.
• Horizontal rule. --- on its own line.

If your posts are written mostly out of these blocks — which is true of most blogs, most cornerstone content, most news sites, most editorial archives — you can edit them as markdown without losing anything important on the way back. This is what makes the edit-with-Claude workflow and the bulk SEO sweep viable in practice.

What comes through as opaque HTML

Here’s the honest part. WordPress has a thriving ecosystem of page builders — Elementor, Divi, Beaver Builder, Bricks, WPBakery — that store their own block formats inside the post. Some core blocks (galleries, embeds, columns, cover, group) also serialize as structured Gutenberg HTML that doesn’t have a natural markdown equivalent.

Specter does not lossily flatten those. They round-trip as raw HTML inside the markdown file. You’ll see the original <!-- wp:elementor/... --> or <div class="wp-block-..."> block preserved verbatim. The block goes back to WordPress unchanged.

The practical implication is straightforward: you can leave those blocks alone safely, but you should not ask an AI to “rewrite this post” if it’s mostly an Elementor layout. The AI will see HTML, try to rewrite it, and most likely break the layout. What it can do safely is rewrite the paragraph text inside a paragraph block sitting between two Elementor sections — the paragraph is normal markdown even when the rest of the post isn’t.

A short list of what to expect:

• Elementor, Divi, Beaver Builder, WPBakery sections. Round-trip as opaque HTML. Leave them; don’t rewrite them.
• Gutenberg cover, gallery, columns, group blocks. Round-trip as structured HTML. Editable if you know the markup; safest to leave alone.
• Shortcodes. Preserved as text ([shortcode attr="value"]). They go back exactly as they came in.
• Reusable blocks / Synced patterns. Preserved by reference. The reference goes back unchanged.
• Custom HTML blocks. Preserved verbatim.

What this means for editing

The mental model is “text where there’s text, opaque where there’s structure.” Most of the editing you actually care about — copy, headings, meta, links, intros, calls to action — happens in the text parts. Those parts are clean markdown. The structural and design parts that aren’t really text are preserved untouched.

In practice that means:

• Body copy edits, intro rewrites, voice passes, fact updates, link insertion — all safe on standard blocks. This is where AI editing earns its keep.
• Layout changes, design tweaks, page-builder restructuring — do those in wp-admin. Markdown is the wrong tool for visual layout, and Specter doesn’t pretend otherwise.
• Frontmatter edits — title, slug, categories, tags, status, meta title, meta description, featured image — are always safe regardless of how the body is built. This is why a bulk SEO sweep across page-builder pages is still useful: the SEO fields live above the blocks.

A practical recommendation

If your site is mostly editorial — paragraphs, headings, lists, images — treat Specter as a full editing environment. Write, rewrite, refactor in markdown, sync back, done.

If your site is mostly page-builder layouts, treat Specter as a content-and-metadata editing environment. Use it for SEO sweeps, meta updates, frontmatter changes, and edits to the text inside individual paragraph blocks. Do layout work in wp-admin where the builder lives.

And if a particular post does something unusual — a custom block, a builder you don’t recognize, a shortcode you’re not sure about — sync down, look at the markdown, and decide before you edit. The file is plain text. Reading it costs nothing and tells you exactly what you’re working with.

The honest summary

The Block Editor is not a markdown editor, and pretending otherwise would break sites. What Specter does instead is preserve what doesn’t translate and translate what does. Standard Gutenberg posts are fully editable as clean markdown. Page-builder posts come back exactly as they left. That trade lets you do real editing work in a folder without surprising your live site.