Skip to content
All posts

Substack Markdown: Editor Shortcuts & a Newsletter Publishing Workflow (2026)

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.

Substack's editor is a rich-text WYSIWYG, but it quietly understands Markdown shortcuts — type ## and you get a heading, **bold** becomes bold, > starts a quote. For writers who think in Markdown, that means you can compose newsletters at full speed without hunting through a toolbar.

This guide documents every shortcut Substack recognizes, the formatting it can't do, and a clean Markdown → Substack workflow for drafting elsewhere and pasting in.

Markdown shortcuts Substack recognizes

Type these in the Substack post editor and they convert on the fly:

You typeResult
# Heading (large)
## Heading (medium)
### Heading (small)
**bold**bold
*italic* or _italic_italic
~~strike~~strikethrough
* or - bulleted list
1. numbered list
> block quote
`code`inline code
```code block
[text](url)link
---horizontal divider

Substack's shortcut support is noticeably better than Medium's — three heading levels, strikethrough, and link auto-conversion all work while typing.

What Substack does NOT support

FeatureStatusWorkaround
Tables❌Use an image, or restructure as a list
Code syntax highlighting❌Plain monospace only; embed a Gist for color
Footnotes✅ via UIUse the footnote button, not [^1]
Nested lists⚠️ limitedKeep shallow
Raw HTML❌Not in standard posts
Mermaid / diagrams❌Paste a rendered image

The two gaps that bite technical newsletters are tables and highlighted code. Tables must become images or lists; code stays monospace unless you embed an external Gist or screenshot.

Pasting Markdown into Substack

Substack handles pasted rich text well, and pasted plain-text Markdown gets partially auto-converted. For best fidelity:

  1. Draft in the Markdown editor.
  2. Convert to clean HTML with Markdown to HTML.
  3. Open the HTML in a browser, select all, copy, and paste into the Substack editor.

Substack maps the semantic HTML (headings, bold, lists, links, blockquotes, images) to its native blocks. This beats pasting raw .md, where some inline syntax survives but block structure can drift.

The newsletter publishing pipeline

  1. Draft in Markdown with live preview in the editor.
  2. Tighten the subject/preview line — generate a one-sentence summary with Markdown to plain text.
  3. Audit structure with the heading audit: one H1 (your title), logical H2/H3, no skipped levels.
  4. Check links with the link checker — broken links in a newsletter can't be edited after send for some recipients.
  5. Convert and paste rendered HTML into Substack.
  6. Add the call-to-action (subscribe button, share link) in Substack's UI.

Subject line and preview text

Substack's subject line is your email's biggest SEO/open-rate lever. Keep it under ~60 characters; write the preview text deliberately rather than letting Substack auto-pull the first sentence. Draft both as plain text — the Markdown to plain text tool strips formatting from a candidate intro paragraph instantly.

Handling code in newsletters

Substack code blocks are plain monospace — no language highlighting. Options:

  1. GitHub Gist embed — paste the Gist URL; Substack renders an embed with highlighting.
  2. Carbon / ray.so screenshot — styled image of code (not selectable).
  3. Plain code block — fine for short commands and config.

Pull every fenced block from your draft with the code block extractor to move them into a Gist quickly.

Images, footnotes, and embeds

  • Images: drag into the editor or paste; always add a caption and alt text. Audit your draft's images with the image audit before converting.
  • Footnotes: use Substack's built-in footnote button — it renders proper numbered references and a footer. Don't type [^1]; it won't convert.
  • Embeds: paste a YouTube, Tweet/X, or Gist URL on its own line for an auto-embed.

Substack vs Medium vs WordPress

FeatureSubstackMediumWordPress
Markdown shortcuts✅ strong✅ partial✅ (Gutenberg)
Heading levels326
Strikethrough shortcut✅❌✅
Tables❌❌✅
Email delivery✅ native❌plugin
Paywall / subscriptions✅ nativepartialplugin

Substack wins for paid newsletters with the best shortcut support of the three hosted platforms. For tables and highlighted code, pair it with your own WordPress site or external embeds.

Common Substack Markdown mistakes

1. Typing [^1] for footnotes. Use the editor's footnote button instead.

2. Expecting tables. They don't render — convert to an image or a list.

3. Code highlighting. Plain blocks have none; embed a Gist for color.

4. Pasting raw Markdown and shipping it. Convert to HTML and paste rich text for clean structure.

5. Ignoring the preview line. Auto-pulled previews are often weak — write it yourself.

6. Too many heading levels. Substack has three — flatten H4+ to bold lead-ins.

Quick reference

GoalOn Substack
Headings# ## ###
Bold / italic**b** / *i*
Strikethrough~~text~~
Lists* / 1.
Quote>
Link[text](url)
Divider---
FootnotesUI button (not [^1])
Highlighted codeEmbed a Gist
TablesImage or list

Substack has the friendliest Markdown shortcuts of any hosted newsletter platform. Draft in Markdown, flatten to three heading levels, paste rendered HTML for clean structure, and reserve Gist embeds for code — your issues go out polished every time.

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

Keep reading

Hand-picked articles related to this one.