Skip to content
All posts
6 min read
markdown
wordpress
cms
publishing
guide

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

MethodBest forSetup
Gutenberg shortcutsWriting directly in WPNone — built in
Jetpack MarkdownFull Markdown documents & codeInstall/enable Jetpack
Import .mdMigrating existing contentPlugin or paste

Method 1: Gutenberg block shortcuts

The default WordPress block editor converts Markdown shortcuts into blocks the moment you type them:

You typeBecomes
## 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:

  1. Install and connect Jetpack (or use a standalone Markdown plugin like WP Githuber MD).
  2. Go to Jetpack → Settings → Writing and enable Markdown.
  3. 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:

  1. Draft in the Markdown editor with live preview.
  2. Lint structure with the heading audit (one H1, no skipped levels) and link checker.
  3. Convert to clean HTML with Markdown to HTML — sanitized, standalone.
  4. Paste the HTML into a Gutenberg Custom HTML block, or the Markdown into a Jetpack Markdown block.
  5. 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

ElementHow to get it right
Single H1WordPress uses the post title as H1 — start body content at H2
Meta descriptionGenerate from intro with Markdown to plain text
Image alt textAlways set in the media library; audit with image audit
Internal linksAdd contextual links; verify with link checker
SlugsClean, 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.comSelf-hosted (.org)
Markdown built in✅ (toggle in settings)via Jetpack/plugin
Custom HTML block✅✅
REST API✅✅
Plugins for .md importlimited (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.

Quick reference

GoalPath
Write fast in WPGutenberg Markdown shortcuts
Paste full Markdown docsJetpack Markdown block
Bulk migrate .mdImporter plugin / REST API
Highlighted codeJetpack or highlighter plugin
Clean HTML to pasteMarkdown to HTML
Fix frontmatter fieldsFrontmatter 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.