Skip to content
All posts

Medium and Markdown: Shortcuts, Import & a Clean Publishing Workflow (2026)

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.

Medium is famously not a Markdown editor. There's no source view, no fenced code highlighting the way GitHub does it, and pasting raw Markdown gives you literal ## and ** on the page. But writers who think in Markdown aren't stuck — Medium's editor recognizes a handful of Markdown-style shortcuts, and the import workflow lets you draft anywhere and publish clean.

This guide covers exactly what Medium's editor accepts, the import-from-URL trick that preserves formatting, and a repeatable Markdown → Medium pipeline.

What Medium's editor actually accepts

Medium converts a few Markdown shortcuts as you type — but only at the start of a line or around a selection:

You typeResult
# then textLarge title (H1)
## then textSmaller title (H2)
* or - Bulleted list
1. Numbered list
> Block quote
*text*bold (on the fly)
_text_italic
`code`inline code
```code block
---section divider

These work while typing in Medium's editor. They do not work when you paste a finished Markdown document — pasted ## stays as literal text.

What Medium does NOT support

FeatureStatusWorkaround
Pasting raw Markdown❌Import from URL, or paste rendered HTML
Tables❌Screenshot, embed, or use a code block
Code syntax highlighting❌Embed a GitHub Gist
Nested lists⚠️ limitedKeep lists shallow
Footnotes❌Inline parentheticals
Custom HTML❌Use embeds (Gist, CodePen, etc.)

Medium's biggest gaps for technical writers are tables and highlighted code. The standard fix for code is embedding a GitHub Gist — paste the Gist URL on its own line and Medium turns it into a highlighted, scrollable block.

The import-from-URL trick

Medium can import a published article and convert its HTML into a native Medium story, preserving headings, lists, bold, links, and images:

  1. Publish your post as a simple HTML page anywhere (a gist, a static host, even a draft on your own site).
  2. In Medium, go to your profile menu → Stories → Import a story.
  3. Paste the URL. Medium fetches the page and rebuilds it as an editable draft.
  4. Clean up, add a code Gist where needed, and publish.

This is the highest-fidelity way to get Markdown content into Medium, because Medium's importer is good at mapping clean semantic HTML to its own blocks.

The reliable Markdown → Medium pipeline

  1. Draft in the Markdown editor with live preview.
  2. Lint with the heading audit — Medium has only two heading levels, so flatten H3+ into H2 or bold lead-ins.
  3. Convert to clean HTML with Markdown to HTML.
  4. Either host that HTML and use Import a story, or open the rendered HTML in a browser, select-all, and paste into Medium (Medium maps pasted rich text reasonably well — better than raw Markdown).
  5. Swap code blocks for GitHub Gist embeds.
  6. Add a subtitle and tags in Medium's UI.

Heading levels: flatten first

Medium supports only two heading sizes (Title and Subtitle/H2 styling). A document with H1→H4 needs flattening:

  • Keep your one H1 as the story title.
  • Promote important H2s; demote H3/H4 to bold lead-in lines.

Run the heading audit to see your hierarchy before you flatten.

Handling code on Medium

Medium's inline code block has no language highlighting. Your options, best to worst:

  1. GitHub Gist embed — paste the Gist URL on its own line. Full highlighting, line numbers, scrollable. Best for real code.
  2. Carbon / ray.so image — a styled screenshot of code. Pretty, but not selectable or accessible.
  3. Medium code block — plain monospace, no colors. Fine for one-liners and config.

Extract every fenced block from your draft with the code block extractor, push them to a Gist, and embed.

SEO and discoverability on Medium

ElementHow Medium handles it
Title tagStory title
Meta descriptionSubtitle (set it deliberately)
TagsUp to 5 — choose high-traffic topics
Canonical URLSet it if cross-posting from your own blog
Reading timeAuto-calculated by Medium

Cross-posting tip: if the article also lives on your own site, set the canonical URL in Medium's story settings to your site's version, so search engines credit the original. Pre-compute reading time with the reading time estimator to match Medium's badge expectations.

Generate a tight subtitle/meta description from your intro with Markdown to plain text.

Medium vs WordPress vs Substack

FeatureMediumWordPressSubstack
Raw Markdown paste❌via Jetpack✅ shortcuts
Heading levels263
Tables❌✅❌
Code highlightingGist embedplugin❌
Import from URL✅importer❌
Canonical URL control✅✅✅

Medium trades formatting control for reach and a built-in audience. If you need tables and highlighted code natively, WordPress or your own site is a better home, with Medium as a canonical-linked repost.

Common Medium Markdown mistakes

1. Pasting raw Markdown. It shows literal ## and **. Import from URL or paste rendered HTML instead.

2. Expecting H3–H6. Medium has two heading levels — flatten deeper hierarchies.

3. Code without a Gist. Plain code blocks have no highlighting. Embed a Gist for anything longer than a line.

4. Forgetting the canonical URL. Cross-posting without it can split SEO value between Medium and your site.

5. Tables. They don't exist. Use a Gist, an image, or restructure as lists.

Quick reference

GoalOn Medium
Headings# / ## while typing
Bold / italic*text* / _text_
Lists* / 1.
Quote>
Divider---
Highlighted codeEmbed a GitHub Gist
Full doc importImport a story (from URL)
TablesNot supported — restructure

Medium rewards clean structure over Markdown fidelity. Draft in Markdown, flatten to two heading levels, swap code for Gists, and use Import-a-story — and your stories publish looking native, no manual reformatting.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.