WordPress Markdown: Gutenberg Shortcuts, Jetpack & Import Workflows (2026)
Write WordPress posts in Markdown — block editor keyboard shortcuts, enabling Jetpack Markdown, importing .md files, and a clean Markdown → WordPress publishing pipeline.
WordPress powers a huge share of the web, and while it isn't a Markdown-first platform, you can absolutely write in Markdown — three different ways. The block editor (Gutenberg) understands Markdown shortcuts as you type, Jetpack adds full Markdown documents, and you can import .md files wholesale. Knowing which path fits your workflow saves hours of reformatting.
This guide covers all three, plus a reliable pipeline for drafting in a real Markdown editor and publishing clean posts to WordPress.
Three ways to use Markdown in WordPress
| Method | Best for | Setup |
|---|---|---|
| Gutenberg shortcuts | Writing directly in WP | None — built in |
| Jetpack Markdown | Full Markdown documents & code | Install/enable Jetpack |
Import .md | Migrating existing content | Plugin or paste |
Method 1: Gutenberg block shortcuts
The default WordPress block editor converts Markdown shortcuts into blocks the moment you type them:
| You type | Becomes |
|---|---|
## | Heading 2 block |
### | Heading 3 block |
* or - | List block (bulleted) |
1. | List block (numbered) |
> | Quote block |
``` | Code block |
--- | Separator block |
**bold** | bold inline |
*italic* | italic inline |
`code` | inline code |
[text](url) | link |
This is the fastest way to write WordPress posts if you think in Markdown. The catch: the shortcuts transform into blocks and the raw Markdown is gone — WordPress stores Gutenberg block HTML, not Markdown source. You can't round-trip back to .md without a converter.
Tip: type / in any empty block to open the block inserter — faster than reaching for the mouse for tables, images, and embeds that have no Markdown shortcut.
Method 2: Jetpack Markdown (full documents)
For real Markdown — including fenced code blocks with syntax highlighting and pasting entire .md files — enable the Markdown module:
- Install and connect Jetpack (or use a standalone Markdown plugin like WP Githuber MD).
- Go to Jetpack → Settings → Writing and enable Markdown.
- In the Classic editor, write Markdown directly. In Gutenberg, add a Markdown block (
/markdown).
Now this renders correctly:
## Release notes
**Highlights**
- New REST API
- Faster builds
```js
const x = await render(md);
```
> Breaking change: old endpoint removed.
Jetpack converts Markdown to HTML at save time and preserves the Markdown source so you can keep editing. This is the closest WordPress gets to a Markdown-native experience.
Method 3: Importing .md files
Migrating a docs site, a Hugo blog, or a folder of .md files into WordPress:
- Paste into a Markdown block (Jetpack) for one-off posts.
- Use an importer plugin that maps frontmatter (
title,date,tags) to WordPress fields for bulk migration. - For programmatic migration, push posts via the WordPress REST API with content pre-rendered to HTML.
Frontmatter mapping matters most:
---
title: "My Post"
date: 2026-05-12
categories: ["Guides"]
tags: ["markdown", "wordpress"]
---
Map title → post title, date → publish date, categories/tags → taxonomies. Clean your frontmatter first with the frontmatter editor so every file has consistent fields.
The reliable publishing pipeline
The most predictable workflow keeps your source in Markdown and only converts at the end:
- Draft in the Markdown editor with live preview.
- Lint structure with the heading audit (one H1, no skipped levels) and link checker.
- Convert to clean HTML with Markdown to HTML — sanitized, standalone.
- Paste the HTML into a Gutenberg Custom HTML block, or the Markdown into a Jetpack Markdown block.
- Optimize — extract a meta description with Markdown to plain text and a reading-time badge with the reading time estimator.
For agencies and multi-author teams, automate steps 2–3 with the API: validate with the validate endpoint, render with the render endpoint, then POST to the WordPress REST API.
Code blocks and syntax highlighting
Vanilla WordPress code blocks are plain <pre>. For highlighted code you need:
- Jetpack Markdown (handles fenced code), or
- A syntax-highlighting plugin (Prism/highlight.js based), or
- A Gutenberg Code block plus a highlighter theme.
Always include the language hint in your fences so the highlighter knows the grammar:
```python
def render(md): ...
```
Extract and sanity-check every fenced block before publishing with the code block extractor.
SEO essentials for WordPress + Markdown
| Element | How to get it right |
|---|---|
| Single H1 | WordPress uses the post title as H1 — start body content at H2 |
| Meta description | Generate from intro with Markdown to plain text |
| Image alt text | Always set in the media library; audit with image audit |
| Internal links | Add contextual links; verify with link checker |
| Slugs | Clean, keyword-focused; preview with slug generator |
Critical gotcha: if you paste content with an # H1, you'll have two H1s (post title + body) — an SEO and accessibility problem. Start your Markdown body at ##.
WordPress.com vs self-hosted
| WordPress.com | Self-hosted (.org) | |
|---|---|---|
| Markdown built in | ✅ (toggle in settings) | via Jetpack/plugin |
| Custom HTML block | ✅ | ✅ |
| REST API | ✅ | ✅ |
Plugins for .md import | limited (plan-gated) | ✅ full |
WordPress.com has Markdown a toggle away; self-hosted gives you full plugin freedom for bulk imports and custom highlighting.
Common WordPress Markdown mistakes
1. Double H1. Post title is already H1 — never start body content with #.
2. Expecting raw Markdown to render. Without Jetpack/a plugin, pasted Markdown shows as literal text. Use a Markdown block or convert to HTML first.
3. Losing source on Gutenberg shortcuts. Shortcuts become blocks; the Markdown is discarded. Keep your .md originals in version control.
4. Unsanitized HTML paste. Pasting raw HTML from unknown sources can carry junk attributes. Use Markdown to HTML which sanitizes output.
5. Broken relative links after import. .md relative paths (../docs/x.md) don't map to WordPress URLs — rewrite them. The URL extractor lists every link to fix.
Related articles
- Markdown to HTML guide — the conversion step in depth
- Docs-as-code guide — version-controlled content workflows
- Medium Markdown guide — another publishing platform's quirks
- Substack Markdown guide — newsletter publishing
- GitHub README guide — source format for technical posts
Quick reference
| Goal | Path |
|---|---|
| Write fast in WP | Gutenberg Markdown shortcuts |
| Paste full Markdown docs | Jetpack Markdown block |
Bulk migrate .md | Importer plugin / REST API |
| Highlighted code | Jetpack or highlighter plugin |
| Clean HTML to paste | Markdown to HTML |
| Fix frontmatter fields | Frontmatter editor |
WordPress will happily take your Markdown — you just pick the on-ramp. Use Gutenberg shortcuts for quick writing, Jetpack for full documents, and the convert-then-paste pipeline when SEO cleanliness matters most.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
Substack's editor supports Markdown shortcuts for headings, bold, lists, quotes, and links. Here's exactly what works, what doesn't, and how to draft newsletters in Markdown and paste clean.
Medium has no true Markdown editor — but keyboard shortcuts, the import-from-URL trick, and a paste pipeline let you draft in Markdown and publish clean stories without reformatting.
A tutorial for authoring and publishing polished Markdown — generate a table of contents, manage frontmatter, add reading-time and callouts, create README badges, and present from Markdown.