Start with WordPress's native paste behavior. Use plain-text Markdown paste for raw Markdown, and convert to Gutenberg blocks only when long-form or repeatable publishing needs more control.
Contents (10)
ChatGPT or Claude can produce a clean Markdown article, but WordPress Gutenberg uses a different document model.
If you paste raw Markdown directly, headings, lists, or tables may not become the blocks you expected. If you ask the AI to generate WordPress block markup instead, you create a different problem: now you must verify that the AI changed only the format and did not also change the article.
A more stable workflow is:
AI draft → reviewed Markdown → Gutenberg block conversion → final WordPress editing
First use WordPress's native paste paths
For short AI-written content, start with the rendered answer and ordinary paste. If Gutenberg creates sensible paragraphs, headings, and lists, stop there.
For raw Markdown, Gutenberg also has a Markdown conversion path through plain-text / match-format paste. Gutenberg issue #70065 describes Markdown being parsed when content is pasted as plain text (commonly Ctrl/Cmd + Shift + V). At the same time, the broader Markdown paste experience is still an active area of improvement in the Gutenberg project.
So a practical order is:
| Source | Try first | Escalate when |
|---|---|---|
| Rendered ChatGPT / Claude answer | Regular paste | Block structure is inconsistent |
| Raw Markdown | Paste as plain text / Match Format | Unsupported syntax or long-form repeatability is a problem |
| Long Markdown source used repeatedly | Deterministic Gutenberg block conversion | You need the same block mapping every time |
| Theme/plugin-specific content | Add it inside WordPress | It is not part of portable Markdown |
A short article does not need Yomu just because it started as Markdown. Use a converter when native paste is not reliable enough for your workflow.
References:
- Gutenberg issue #70065: Pasting Markdown as plain text
- Gutenberg issue #77064: Improve Markdown support
Why Gutenberg is different from Markdown
Markdown represents structure with text syntax:
## Findings
**Conclusion:** choose A.
- Reason one
- Reason two
Gutenberg represents content as blocks and serializes those blocks into HTML with WordPress block comments.
Conceptually, a paragraph block looks like:
<!-- wp:paragraph -->
<p>This is a paragraph.</p>
<!-- /wp:paragraph -->
A heading is a Heading block, a list is a List block, and a table is a Table block.
So the reliable conversion is not "remove Markdown symbols." It is map the meaning of the Markdown structure to Gutenberg's block structure.
A practical workflow
Yomu can be used as the intermediate step.
1. Keep the article in Markdown
Ask the AI for normal Markdown rather than WordPress-specific code.
For example:
Write the article in Markdown.
Do not repeat the article title in the body.
Use H2 for major sections and H3 for subsections.
Review facts, links, wording, and heading hierarchy before conversion.
2. Preview the Markdown first
Before debugging WordPress, make sure the Markdown itself is correct.
Check:
- heading levels
- nested lists
- tables
- code fences
- links
- quotes
If the source is wrong, converting it only moves the error downstream.
3. Convert the standard elements to Gutenberg blocks
Typical mappings are:
| Meaning | Markdown | Gutenberg |
|---|---|---|
| Paragraph | plain text | Paragraph block |
| Heading | ##, ### |
Heading block |
| List | -, 1. |
List block |
| Quote | > |
Quote block |
| Code | fenced code | Code block |
| Table | pipe table | Table block |
The output should use WordPress block serialization rather than plain HTML if you want Gutenberg to keep treating each element as a native block.
4. Paste through WordPress's Code Editor
In the WordPress Block Editor, switch to Code editor and paste the generated block markup into a draft.
Then switch back to the visual editor.
Check that paragraphs, headings, lists, quotes, code, and tables are recognized as separate blocks.
5. Save and reload before trusting it
A block can look correct initially but still be invalid after WordPress parses and serializes it.
Save the draft, reload the page, and make sure WordPress does not report invalid or unexpected block content.
Plain HTML is not the same as Gutenberg block markup
Markdown converted to ordinary HTML might produce:
<h2>Findings</h2>
<p>Body text.</p>
That can display correctly.
But if your goal is to continue editing with Gutenberg as native blocks, block markup is usually a better intermediate format because the block boundaries remain explicit.
What should stay in WordPress
Do not try to encode every WordPress feature in your Markdown source.
Add these in WordPress after the core article is imported:
- media-library images
- theme-specific blocks
- CTA blocks
- product boxes
- plugin-specific FAQ blocks
- embeds
- layout-specific components
The Markdown source should hold the article's content and structure, not every CMS-specific UI element.
Images need a separate publishing step
A Markdown image reference:
does not upload that image to WordPress.
The file still needs to be added to the WordPress media library or otherwise hosted where WordPress can use it.
Treat text conversion and media publishing as separate tasks.
Tables: conversion success is not the end
A Markdown table can become a Gutenberg Table block and still be difficult to read on mobile.
After conversion, check:
- column count
- long URLs
- cell length
- horizontal overflow
- whether the conclusion should also be stated outside the table
Technical validity and editorial readability are different checks.
Why I do not ask the AI to generate Gutenberg markup every time
An AI can generate Gutenberg-style markup, but format conversion is a deterministic job.
If the goal is only to change representation, letting the AI rewrite the entire article creates additional review work.
It is easier to verify this pipeline:
AI creates Markdown
↓
Human reviews content
↓
Converter maps structure
↓
WordPress final edit
The AI handles the generative part. The converter handles the predictable mapping.
Privacy for unpublished content
If the article is unpublished or work-related, check where conversion happens.
Yomu's core Markdown conversion workflow is designed to run in the browser rather than send the document body to a conversion server.
That is one reason to separate deterministic conversion from server-side AI generation when AI is no longer needed.
Summary
If direct paste from the rendered AI answer works, use it.
If native paste is not reliable enough for a long or repeatable workflow, keep Markdown as the source, convert its structure to Gutenberg blocks, import through the Code Editor, then finish media and site-specific components inside WordPress.
This keeps the article content separate from the CMS-specific representation.