← Back to Blog

The Complete Guide to Converting Markdown to Substack

Formatting

Markdown is the default writing format for a growing share of newsletter authors. It’s fast, distraction-free, portable, and works with virtually every text editor and writing tool. But Substack’s editor doesn’t accept markdown directly — it’s a rich text editor that expects formatted input.

This creates a gap. You write in markdown because it’s efficient. You publish on Substack because it’s where your audience is. Getting content from one to the other without losing formatting is the challenge this guide solves.

Why Writers Use Markdown

Before diving into the conversion process, it’s worth understanding why markdown has become the preferred format for so many writers.

Speed

Markdown lets you format as you write. Instead of reaching for a toolbar button, you type **bold** or ## Heading and keep moving. Once the syntax becomes muscle memory, it’s significantly faster than point-and-click formatting.

Portability

A markdown file is plain text. It opens in any editor on any operating system. Your content isn’t locked into a proprietary format — you can move between tools freely. If you ever leave Substack, your drafts come with you.

Version Control

Markdown files work with version control systems like Git. For writers who want a history of every draft revision, this is a powerful feature that rich text editors can’t match.

AI Compatibility

Most AI writing assistants (Claude, ChatGPT, and others) output markdown by default. If you use AI to draft, outline, or edit your newsletter, the output is already in markdown format.

Focus

Markdown editors tend to be minimal — no toolbars, no menus, just text. This distraction-free environment helps writers stay in flow.

What Transfers Cleanly to Substack

When you convert markdown to rich text and paste it into Substack, most elements work without issues:

Headings

# Heading 1
## Heading 2
### Heading 3

Substack supports three heading levels. H1 maps to the post title (used automatically), while H2 and H3 are available in the body. Most writers use H2 for main sections and H3 for subsections.

Bold and Italic

**bold text**
*italic text*
***bold and italic***

These transfer perfectly. Substack’s rich text editor uses the same bold and italic styling you’d expect.

[link text](https://example.com)

Inline links convert cleanly. Substack renders them as underlined, clickable links in both the web view and email.

Unordered Lists

- First item
- Second item
  - Nested item
- Third item

Bullet lists work well. Substack supports one level of nesting.

Ordered Lists

1. First step
2. Second step
3. Third step

Numbered lists transfer correctly and maintain their sequence.

Blockquotes

> This is a blockquote.
> It can span multiple lines.

Blockquotes render with Substack’s distinctive left-border styling.

Horizontal Rules

---

Horizontal rules convert to Substack’s section dividers.

Images

![Alt text](https://example.com/image.png)

Images work if they’re hosted at accessible URLs. Substack will typically re-host the image on its own CDN.

What Breaks or Needs Workarounds

Several markdown elements don’t survive the conversion to Substack:

Tables

This is the biggest pain point. Markdown tables:

| Column A | Column B |
|----------|----------|
| Data 1   | Data 2   |

These do not render in Substack. The platform strips HTML tables, so even if your markdown converter outputs valid table HTML, Substack won’t display it.

Workaround: Convert tables to images before pasting into Substack. Tools like DownStack handle this automatically — tables in your markdown are rendered as styled images, hosted on a CDN, and embedded in the output.

Footnotes

Here is a statement[^1].

[^1]: This is the footnote text.

Standard markdown footnotes don’t convert to Substack’s footnote system. Substack has its own built-in footnote feature (accessible via the editor toolbar), but it uses a different mechanism than markdown footnotes.

Workaround: Add footnotes manually using Substack’s editor after pasting your converted content, or use inline parenthetical references instead.

Syntax-Highlighted Code Blocks

```python
def hello():
    print("Hello, world!")
```

Basic code blocks transfer to Substack, but syntax highlighting (colored keywords) does not. Substack renders code blocks in a monospace font with a grey background, but without language-specific coloring.

Workaround: For code-heavy posts, consider using screenshots of syntax-highlighted code from your editor.

Task Lists

- [x] Completed task
- [ ] Incomplete task

GitHub-flavored markdown task lists don’t convert. They’ll render as regular list items, losing the checkbox formatting.

Strikethrough

~~strikethrough text~~

Strikethrough support is inconsistent. Some markdown converters will output the HTML <del> tag, which Substack may or may not render depending on the context.

HTML Embeds

<iframe src="..."></iframe>
<div class="custom">...</div>

Raw HTML in markdown is stripped by Substack’s sanitizer. Embeds need to be added through Substack’s native embed feature after pasting.

The Conversion Workflow

Here’s a practical, step-by-step workflow for getting markdown into Substack:

Step 1: Write Your Draft in Markdown

Use any markdown editor: VS Code, Obsidian, iA Writer, Typora, Bear, or even a plain text file. Focus on content without worrying about Substack-specific formatting.

Step 2: Convert Markdown to Rich Text

You need a tool that converts markdown to rich text that Substack’s editor can accept. Options include:

  • DownStack — purpose-built for the markdown-to-Substack workflow, with automatic table-to-image conversion and permanent hosting
  • Marked.js or similar — render markdown to HTML in a browser, then copy the rendered output
  • Pandoc — command-line tool that converts between document formats
  • Dillinger or StackEdit — online markdown editors with live preview

Step 3: Copy and Paste into Substack

Select the rendered rich text (not the raw HTML) and paste it into Substack’s editor. The formatting should carry over for supported elements.

Step 4: Fix What Didn’t Transfer

Review the pasted content and fix anything that broke:

  • Add tables as images (if not already handled by your conversion tool)
  • Re-add footnotes using Substack’s native feature
  • Add embeds (YouTube, Twitter, etc.) using Substack’s embed blocks
  • Check heading levels — make sure H2 and H3 are correct
  • Verify all links are working

Step 5: Preview and Publish

Use Substack’s preview feature to check how the post looks in both web and email format. Pay particular attention to:

  • Image sizing and placement
  • Table image readability on mobile
  • Code block formatting
  • Blockquote rendering

Common Gotchas

Copy the Rendered Output, Not the HTML Source

When converting markdown, you want to copy the visually rendered rich text — not the underlying HTML code. If you paste raw HTML into Substack, it will appear as code text rather than formatted content.

Watch for Double Spacing

Some markdown editors add extra line breaks between paragraphs. When pasted into Substack, this can create unwanted double spacing. Remove extra blank lines before pasting.

Image URLs Must Be Public

If your markdown references images on localhost, a private server, or behind authentication, they won’t display in Substack. All image URLs must be publicly accessible.

Heading Hierarchy Matters

Substack uses H2 as the primary section heading in the post body (H1 is reserved for the title). If your markdown uses H1 for sections, you’ll need to downshift all headings by one level.

Optimizing Your Workflow

For writers who publish regularly in markdown, optimizing the conversion pipeline is worth the investment:

Batch Processing

If you write multiple posts ahead of time, convert them all in one session rather than one at a time. This reduces context-switching between your markdown editor and Substack.

Template Your Frontmatter

Create a markdown template with your standard post structure — title, subtitle, sections, CTA. This speeds up the drafting process and ensures consistency.

Automate Table Handling

If your newsletter regularly includes data tables, automating the table-to-image conversion eliminates the biggest friction point. DownStack was built specifically for this use case, converting markdown tables to permanently hosted images in a single step.

Keep a Pre-Flight Checklist

Before hitting publish, run through a quick checklist:

  • All links working
  • Images loading correctly
  • Tables displaying as images
  • Heading hierarchy correct
  • Preview checked in both web and email views
  • Subtitle/meta description set

Key Takeaways

  • Markdown is the preferred writing format for many newsletter authors due to speed, portability, and AI compatibility
  • Most markdown elements (headings, bold, italic, links, lists, blockquotes) transfer cleanly to Substack
  • Tables, footnotes, syntax highlighting, and task lists require workarounds
  • The conversion workflow is: write in markdown, convert to rich text, paste into Substack, fix edge cases
  • Always copy the rendered rich text, not the raw HTML source
  • Automating table handling is the single biggest time saver for data-heavy newsletters
  • Preview your post in both web and email format before publishing