You write in markdown. Your blog runs on WordPress. And somewhere in between, things go wrong. Gutenberg mangles your formatting. Images need to be uploaded separately. Code blocks lose their syntax highlighting. You end up spending more time fixing the post than writing it.
It doesn't have to be this way. There are tools that take your markdown and publish it to WordPress directly — handling images, metadata, and formatting automatically. Here's how each approach works, what breaks, and what actually solves the problem.
Why Markdown and WordPress Don't Get Along
WordPress switched to Gutenberg (the block editor) in 2018. Since then, pasting markdown into WordPress has been a gamble. Gutenberg converts some markdown syntax into blocks, ignores the rest, and occasionally creates a mess of nested paragraphs and stray HTML.
The core problem: Gutenberg is a visual block editor. Markdown is a plain-text format. They represent content differently, and WordPress doesn't have a reliable built-in bridge between the two.
Specifically, here's what breaks when you paste markdown into WordPress:
- Images — markdown image references don't get uploaded to your media library. They either point to external URLs (which can break) or get stripped entirely.
-
Code blocks — fenced code blocks become plain
<pre>tags with no syntax highlighting. - Front matter — YAML front matter (title, category, tags) gets treated as regular text content.
- Tables — markdown tables are hit-or-miss. Some convert to HTML tables, some render as plain text.
- SEO metadata — there's no way to set meta descriptions, focus keywords, or Open Graph tags from your markdown file.
Option 1: The Jetpack Markdown Module
Jetpack includes a markdown module that lets you write posts in markdown syntax directly inside the WordPress editor. Enable it under Jetpack → Settings → Writing, and you can use a "Markdown" block in Gutenberg.
Pros: Free. Works inside WordPress. Handles basic markdown syntax (headings, bold, italic, links, lists).
Cons: You're still writing inside WordPress, not in your favorite editor. No image handling — you still upload images manually. No code syntax highlighting. No SEO metadata from markdown. And you need the full Jetpack plugin installed, which is heavy.
Best for: Writers who want markdown syntax but don't mind working inside the WordPress admin panel.
Option 2: Convert Markdown to HTML, Then Paste
Tools like pandoc, Marked, or online markdown converters can turn your .md file into HTML. You then paste the HTML into a Custom HTML block in WordPress.
Pros: Works with any markdown file. You keep writing in your preferred editor. Free.
Cons: Manual process every time you publish. Images still need to be uploaded and linked separately. No featured image generation. No SEO metadata. Code blocks are unstyled HTML. If you update the post, you go through the whole process again.
Best for: Occasional publishers who don't mind the manual work.
Option 3: WordPress REST API with a Script
The WordPress REST API lets you create posts programmatically. You could write a script that reads a markdown file, converts it to HTML, and pushes it to WordPress via POST /wp-json/wp/v2/posts.
import markdown
import requests
with open("my-post.md") as f:
md_content = f.read()
html = markdown.markdown(md_content, extensions=["fenced_code", "tables"])
response = requests.post(
"https://yourblog.com/wp-json/wp/v2/posts",
auth=("username", "xxxx xxxx xxxx xxxx xxxx xxxx"),
json={
"title": "My Blog Post",
"content": html,
"status": "draft",
}
)
Pros: Full control. Can be automated in CI/CD or run from the command line. Free (if you write the script yourself).
Cons: You're building and maintaining your own publishing tool. Image handling requires separate API calls to upload each image, then rewrite the HTML to use the new URLs. Code highlighting requires adding a client-side library. SEO metadata requires the Yoast or Rank Math REST API. Featured images require another API call. Every edge case (tables, embeds, captions) needs custom code.
Best for: Developers who enjoy building tooling and have simple content (mostly text, few images).
Option 4: Desktop Apps with WordPress Publishing
Apps like Ulysses, iA Writer, and MarsEdit let you write in markdown and publish to WordPress from the app. They connect to your WordPress site via the XML-RPC or REST API.
Pros: Beautiful writing environment. Native app performance. Write and publish from the same place.
Cons: Typically macOS/iOS only. No automatic image optimization or media library management — images are uploaded as-is. No syntax highlighting for code blocks. No SEO metadata. No featured image generation. Subscription pricing ($5–$50/month depending on the app).
Best for: Non-technical writers who value a clean writing experience and don't need code blocks or SEO automation.
Option 5: Notipo — Write Markdown, Publish Everything
Notipo is a markdown editor built specifically for WordPress publishing. You write in the built-in editor (or sync from Notion), and Notipo handles the entire pipeline:
- Images — uploaded to your WordPress media library automatically. No broken links, no external hosting.
- Code blocks — fenced code blocks are converted to syntax-highlighted HTML. Works with any theme that loads a highlighter.
- SEO metadata — set focus keywords, meta descriptions, and SEO titles. Notipo writes these to Rank Math or Yoast via their REST APIs.
- Featured images — generated automatically based on your post title and category, or upload your own.
- Categories and tags — set from the editor and applied on publish.
- One-click publish — your markdown goes to WordPress as a fully formatted post with all metadata in a single action.
The difference from the other options: Notipo doesn't just convert markdown to HTML. It handles everything that usually requires manual work after the conversion — the images, the metadata, the featured image, the code highlighting. You write, click publish, and the post is live.
Pricing: Free for up to 5 posts per month. Pro plan is $19/month for unlimited posts.
Which Option Should You Pick?
It depends on how much of the publishing pipeline you want to automate:
- Just want markdown syntax in WordPress? Enable the Jetpack markdown module. It's free and simple.
- Publish occasionally and don't mind manual work? Convert to HTML with pandoc and paste it in. Quick and free.
- Developer who wants full control? Build a REST API script. You'll spend a weekend on image handling, but you own the whole pipeline.
- Writer who wants a beautiful app? iA Writer or Ulysses, if you're on Apple and don't need code blocks.
- Want the full pipeline automated? Notipo handles images, code highlighting, SEO, featured images, and publishing in one step. It's the only option that covers everything.
The manual approaches work fine when you're publishing one post a month. But if you're publishing weekly or more, the time spent on image uploads, formatting fixes, and metadata entry adds up fast. That's where automation pays for itself.
