Markdown to Substack: Publish Without Reformatting Your Draft

Why Markdown needs a conversion step

Substack offers several Markdown-like typing shortcuts—for example, typing a hash and a space can create a heading—but its support documentation distinguishes those shortcuts from full Markdown document support. A shortcut changes the current block as you type. It does not parse an entire pasted .md file with all of its links, tables, fenced code, and images.

The robust handoff format is rich text on the clipboard. It gives the destination editor headings, paragraphs, links, lists, and code as structured HTML while also keeping a plain-text fallback. The final Substack draft still needs a visual check because the destination editor decides which styles and blocks it preserves.

Convert a Markdown draft to Substack in six steps

1. 01

   Finish the content in your usual editor

   Write in Obsidian, VS Code, Cursor, or another Markdown tool. Use one H1 for the post title and H2/H3 headings for the body.

2. 02

   Resolve local-only syntax

   Convert wiki links, transclusions, custom callouts, and local image references into ordinary links, prose, or hosted images before the publishing handoff.

3. 03

   Load the Markdown into StackDraft

   Paste the draft, drag in the .md file, or use the file picker. The editor renders a live preview without uploading the draft.

4. 04

   Review the compatibility checks

   Fix missing image descriptions, heading jumps, wide tables, long code blocks, SVG images, and other patterns that can fail in an email.

5. 05

   Copy title, then copy body

   Paste the plain title into Substack’s title field and the prepared rich-text body into the post editor. This avoids leaving a duplicate H1 at the top of the article.

6. 06

   Preview the actual send

   Check the web preview and send a test email. Open it on a narrow phone screen, click every important link, and inspect every converted asset.

What happens to each Markdown element?

Use portable Markdown before you convert

• Put the publication title in a single H1 on the first meaningful line.
• Use descriptive link text instead of raw URLs when the destination matters.
• Give every image concise alt text inside the Markdown brackets.
• Add a language after each code fence when syntax highlighting helps comprehension.
• Avoid raw HTML for layout; destination editors and email clients routinely sanitize it.
• Keep newsletter tables compact and explain the takeaway in surrounding prose.
• Use public image URLs or upload images during the final Substack review.

# A clear post title

One-sentence promise for the reader.

## The problem

Explain the context in short paragraphs.

## The solution

1. First useful step
2. Second useful step
3. Verification step

## What to remember

End with the practical takeaway.

Fix the most common paste problems

1. 01

   Raw Markdown is showing

   Copy from StackDraft’s prepared body action, not from the Markdown source pane. Substack does not parse a complete pasted Markdown document.

2. 02

   The title appears twice

   Use Copy title for the title field and Copy body for the editor. StackDraft removes the first H1 from the copied body.

3. 03

   An image is missing

   A local relative path only exists on your computer. Upload the source image to Substack, use a public URL, or export and insert the generated asset.

4. 04

   Code or a diagram is hard to read

   Shorten long lines, reduce diagram complexity, increase label contrast, and split a large technical artifact into focused pieces.

5. 05

   Formatting looks different in email

   Treat Substack’s email preview as the final renderer. Simplify any block whose meaning depends on exact spacing, width, or custom styles.

The five-minute pre-publish checklist

• Title is present once and matches the promise in the opening paragraph.
• Heading order forms a useful outline when read by itself.
• Links use public URLs and open correctly.
• Images have useful descriptions and are not carrying essential text alone.
• Tables remain legible at phone width.
• Code blocks wrap or scroll without forcing the whole email wider.
• A test email looks correct in both light and dark viewing environments.
• The post still makes sense when optional decorative formatting is removed.