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 type | Result |
|---|---|
# then text | Large title (H1) |
## then text | Smaller 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
| Feature | Status | Workaround |
|---|---|---|
| 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 | ⚠️ limited | Keep 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:
- Publish your post as a simple HTML page anywhere (a gist, a static host, even a draft on your own site).
- In Medium, go to your profile menu → Stories → Import a story.
- Paste the URL. Medium fetches the page and rebuilds it as an editable draft.
- 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
- Draft in the Markdown editor with live preview.
- Lint with the heading audit — Medium has only two heading levels, so flatten H3+ into H2 or bold lead-ins.
- Convert to clean HTML with Markdown to HTML.
- 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).
- Swap code blocks for GitHub Gist embeds.
- 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:
- GitHub Gist embed — paste the Gist URL on its own line. Full highlighting, line numbers, scrollable. Best for real code.
- Carbon / ray.so image — a styled screenshot of code. Pretty, but not selectable or accessible.
- 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
| Element | How Medium handles it |
|---|---|
| Title tag | Story title |
| Meta description | Subtitle (set it deliberately) |
| Tags | Up to 5 — choose high-traffic topics |
| Canonical URL | Set it if cross-posting from your own blog |
| Reading time | Auto-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
| Feature | Medium | WordPress | Substack |
|---|---|---|---|
| Raw Markdown paste | ❌ | via Jetpack | ✅ shortcuts |
| Heading levels | 2 | 6 | 3 |
| Tables | ❌ | ✅ | ❌ |
| Code highlighting | Gist embed | plugin | ❌ |
| 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.
Related articles
- WordPress Markdown guide — full Markdown via Jetpack
- Substack Markdown guide — newsletters with better shortcut support
- Markdown to HTML guide — the conversion step
- Best Markdown editors — where to draft before publishing
- GitHub README guide — source format for dev articles
Quick reference
| Goal | On Medium |
|---|---|
| Headings | # / ## while typing |
| Bold / italic | *text* / _text_ |
| Lists | * / 1. |
| Quote | > |
| Divider | --- |
| Highlighted code | Embed a GitHub Gist |
| Full doc import | Import a story (from URL) |
| Tables | Not 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.
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.
Write WordPress posts in Markdown — block editor keyboard shortcuts, enabling Jetpack Markdown, importing .md files, and a clean Markdown → WordPress publishing pipeline.
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.