Prepare Markdown for WordPress
Pasting cleaned Markdown into the WordPress block editor works better than most people expect: in a live test on 2026-08-24, the full portability fixture became 62 native Gutenberg blocks, including headings, nested lists, quotes, dividers, fenced code, and GFM tables. The work this tool does is the repair layer around that, because the same paste left the post title empty, turned front matter into stray content, dropped task state, broke a local image, and left footnotes and math as literal text.
Handoff mode: Gutenberg paste. Tested in WordPress.com desktop Block Editor. Tested 2026-08-24.Fixture markdown-portability-test-v1.See the record.
Prepare your draft
Your Markdown
Your draft stays in this browser. Nothing is uploaded.
Source context (optional)
Relative links and local files stay unresolved until you confirm where they point. Each unresolved target gets its own manual step rather than a guess.
How the Gutenberg paste handoff works
Two named modes exist. Gutenberg paste sends cleaned Markdown as plain text for a real paste event, which is what produces native editable blocks. The WordPress.com and Jetpack Markdown Block instead preserves your Markdown source, and in the live test it rendered GFM tables and footnotes with backlinks after the draft was saved. That block has to be available on the site and Markdown has to be enabled, so it is an option rather than a universal answer.
What happens to each construct
| Rule | What happens | Result | Why | Confidence | Last tested |
|---|---|---|---|---|---|
WP-FM-01 | Front matter is removed from the body. | Manual step | Pasted front matter became separators and a stray paragraph in the tested editor. | Verified | 2026-08-24 |
WP-TITLE-01 | The post title is not filled by pasting. | Manual step | The tested paste left the title field empty and kept the H1 in the body. | Verified | 2026-08-24 |
WP-ANCHOR-01 | In-page anchor links will not resolve. | Manual step | The tested editor kept the href but generated no matching heading IDs. | Verified | 2026-08-24 |
WP-LINK-01 | Relative and local links are not resolved. | Manual step | Without a confirmed site base URL there is no safe way to know where these point. | Verified | 2026-08-24 |
WP-IMAGE-01 | Local images do not upload. | Manual step | A local relative image became a broken image block in the tested editor. | Verified | 2026-08-24 |
WP-FOOT-01 | Footnotes are moved to a checklist for Gutenberg paste. | Manual step | Gutenberg left footnote syntax literal. The WordPress.com Markdown Block did render them. | Verified | 2026-08-24 |
WP-MATH-01 | Math is moved to a checklist. | Manual step | Both tested modes left the dollar delimiters as literal text. | Verified | 2026-08-24 |
WP-OBS-01 | Obsidian syntax is flattened to ordinary text. | Manual step | Wiki links, transclusion, callout markers, and block references stayed literal. | Verified | 2026-08-24 |
CORE-LINK-01 | A link with an unsafe scheme was removed; its text was kept. | Degraded | Only http, https, and mailto targets are carried. A javascript:, data:, or protocol-relative target is never copied into a destination editor. | Verified | 2026-08-24 |
WP-MERMAID-01 | Mermaid stays as source code; no diagram renders. | Degraded | Both tested modes showed the fence as a code block. | Verified | 2026-08-24 |
WP-HTML-01 | Raw HTML is removed; its visible text is kept. | Degraded | Gutenberg flattened the details structure and the Markdown Block escaped raw HTML. | Verified | 2026-08-24 |
WP-MODE-01 | Two WordPress modes exist: Gutenberg paste and the WordPress.com/Jetpack Markdown Block. | Changed | Site capabilities differ. The Markdown Block needs that block installed and Markdown enabled. | Verified | 2026-08-24 |
WP-TASK-01 | Task state becomes explicit words. | Changed | Gutenberg dropped checkbox state and the Markdown Block showed literal markers. | Verified | 2026-08-24 |
WP-HEAD-01 | Heading levels are preserved. | Kept | H1 through H6 became native heading blocks in both tested modes. | Verified | 2026-08-24 |
WP-EMPH-01 | Inline formatting is preserved. | Kept | Ordinary emphasis, strike, and inline code converted in the tested paste. | Verified | 2026-08-24 |
WP-LIST-01 | Lists and nesting are preserved. | Kept | Three tested nesting levels became native list blocks. | Verified | 2026-08-24 |
WP-CODE-01 | Code is preserved, but a long unbroken line may overflow. | Kept | Theme CSS controls overflow; tested long lines exceeded a 390-pixel viewport. | Verified | 2026-08-24 |
WP-TABLE-01 | Small tables become native tables. | Kept | Both tested modes rendered the GFM table with header and body cells. | Verified | 2026-08-24 |
WP-TABLE-02 | A wide table needs a narrow-screen check. | Kept | Table behavior depends on the theme and viewport, which this tool cannot see. | Verified | 2026-08-24 |
WP-IMAGE-02 | Remote images are hotlinked, not imported. | Kept | The tested paste linked the external file rather than creating a Media Library asset. | Verified | 2026-08-24 |
Where WordPress usually goes wrong
The post title stays empty
A paste fills the body, never the title field. The leading H1 stays in the body, so you get a title field to fill and a duplicate heading to decide about.
Front matter becomes visible content
The opening and closing dashes became separators and the fields became a paragraph and a list in the tested editor. This tool removes front matter from the body and lists the fields for you to set by hand.
In-page anchor links break
Markdown anchor links kept their href, but the rendered headings had no matching id values, so every internal link pointed at nothing.
Local images arrive broken
A relative image path pasted as an image block whose file never loaded. Remote images are hotlinked rather than added to the Media Library, which leaves licensing and availability with the original host.
Evidence from the test
Limits of what was tested
- One WordPress.com site, one theme, and the current block editor were tested.
- Self-hosted installations, plugins, user roles, the classic editor, multisite, and headless setups were not tested.
- A reliable mobile screenshot could not be captured, so narrow-screen table and code behavior is only partly verified.
- The REST API is documented but authentication, content submission, media upload, and draft readback were not tested.
A live result proves the tested surface on the tested date. Rendering is not identical across platform versions, themes, plugins, or email clients, and link preview cards are controlled by the destination.