Skip to content
newsletterapi
Get access

How to Publish to Substack from Markdown or Obsidian

By the newsletterapi team · Published · Updated · 5 min read

The problem: “Moving my drafts from Obsidian or Markdown into Substack is the worst part of my week.”

Cover image: How to Publish to Substack from Markdown or Obsidian

Short answer

Substack's post editor does not support Markdown as of October 2026, so the reliable route is to render your Markdown first and paste the formatted result, then fix images, code, equations and tables with the editor's own blocks. For whole archives, Substack's importer can read an RSS feed. Fully automated posting needs unofficial tools that use your login, which Substack's terms put at risk.

The problem

"The handoff was the worst part of my week: select all, paste, watch the formatting break, re-upload every image by hand, fix the footnotes." — r/ObsidianMD, August 2026

"There is still no API for writers. There is still no support for Markdown." — @herbertyang on X, September 2026

Lots of writers draft in Obsidian, iA Writer, VS Code or plain Markdown files and publish on Substack. The writing is fine. The handoff isn't. In our review of public Reddit, X, Hacker News and GitHub posts (October 2026), 18 forum and GitHub sources from writers described not being able to publish to Substack from their own tools (Obsidian or Markdown files, old archives, AI drafts), plus 7 separate social posts from writers. Examples include the Obsidian thread above, a writer with 1,000+ TinyLetter posts in Google Docs, and a Hacker News comment arguing that the editor's paste support is the practical answer.

This guide covers what the editor actually accepts, a repeatable paste workflow, bulk imports, where AI agents help, and why fully automated posting is not the safe answer.

Does Substack support Markdown?

No. Substack's help centre says: "We do not currently support Markdown in the post editor" (Substack help). If you paste raw Markdown, you'll see the # and ** characters in your post.

The editor does accept some Markdown-like typing shortcuts (Substack help): #, ## and ### plus a space for headings, * or - for bullets, 1. for numbered lists, > for a quote and --- for a divider. These trigger as you type, so they help when you write in Substack, not when you paste a whole file.

It also can't take raw HTML: Substack does "not currently support custom CSS or HTML in the post editor", including <iframe> code (Substack help).

How do I paste a Markdown draft without breaking it?

Paste rendered text, not source. This is the workflow most writers settle on:

  1. Render the note. In Obsidian, switch to reading view. In other editors, open the Markdown preview.
  2. Copy the rendered output (select all in the preview, copy).
  3. Paste into a new Substack draft. Headings, bold, italics, links, lists and quotes usually come across as formatting.
  4. Fix the elements that don't survive, using the table below.
  5. Preview the email and web versions before you publish.
Markdown element What to do in Substack
Headings, bold, italic, links, lists, quotes Usually survive a rendered paste; spot-check heading levels
Images Drag and drop them into the draft; supported formats are avif, gif, jpg, jpeg, png and webp (help). Add alt text and captions from the image menu (help)
Fenced code Insert More → Code block and paste the code inside; the language is detected automatically (help)
Math ($...$) Insert More → LaTeX and paste the equation (help)
Tables Use a Datawrapper embed, which supports "charts, maps, and tables" (help), or an image
Embeds (YouTube, Spotify, TikTok) Paste the URL on its own line; the embed appears automatically (help)
Footnotes Check each one after pasting; the Obsidian writer above reports they break
Raw HTML or iframes Not supported; replace with a supported embed
Reusable intros, sign-offs, CTAs Save them once as a Substack template (help)

Two more checks for long posts. There's no word limit, but posts over 1,000,000 characters can't be saved, and Gmail clips emails larger than about 102KB, including images and links (Substack help). If you see the "may be truncated" warning, split the post or trim images.

Can I import Markdown posts in bulk?

Not as files, but often through a feed. Substack's post importer reads Medium, Ghost, WordPress, Mailchimp, beehiiv, Seeking Alpha, Tumblr and Blogspot, and "also takes in RSS feeds" from other sites (Substack help). So if your Markdown already publishes to a static site or blog with an RSS feed, you can:

  1. Go to Settings → Import/Export → Import posts.
  2. Paste your site or feed URL and let the importer find your archive.
  3. Confirm you own the content and import. Imported posts appear as web posts.
  4. To email one, edit it and tick "Send via email and the Substack app" (Substack help).

Note the help article's warning that some platforms "will only include the most recent posts, such as the latest 20 posts, in their RSS". For old archives, the manual route is to paste each post and change its publication date afterwards. More detail is in importing posts to Substack.

Where can an AI agent help?

In the drafting and clean-up, not the publish button.

  • Clean-up. An assistant can turn a Markdown file into paste-ready rich text, flag elements that need a code, LaTeX or Datawrapper block, and write alt text for your images.
  • Drafting from your archive. With an MCP server that can read your past posts, an assistant can find related posts to link, match your voice and draft a first version in your editor. See connect Claude to Substack for the setup options.
  • Not publishing. Substack's official MCP is read-only: it "cannot publish posts, send Notes, or modify your account", and it is limited to admins of Bestseller publications (Substack help).

Why not automate the whole push to Substack?

Because there's no official way to do it, and the unofficial ways depend on your login. The Obsidian writer quoted above built a command-line tool and said plainly that "It needs your session cookie because Substack's official API is read only and cannot publish" (r/ObsidianMD). Substack's Terms of Use ban processes "that run or are activated while you are not logged into Substack" and anything "allowing someone else to log into Substack as you". Tools like this also break when Substack changes its internals, sometimes silently. Our Substack 403 error explainer covers why.

For most writers the trade-off isn't worth it. As one Hacker News commenter put it, Substack's "rich text editor DOES accept copy-pasted data - and copy-paste is the universal API" (Hacker News).

What not to do

  • Don't paste raw Markdown and publish without previewing; the symbols will show.
  • Don't give a browser extension or cloud tool your Substack session so it can post for you.
  • Don't import someone else's feed. The importer asks you to confirm you own the publication.
  • Don't skip the email preview on long, image-heavy posts.

Where newsletterapi fits

Our MCP server for AI agents reads your own Substack archive so Claude, ChatGPT and other assistants can learn your voice, suggest internal links and draft with you. It is read-only and independent of Substack, and it does not publish for you. See /mcp for details and how to get access.

Questions people ask

Does Substack support Markdown?
No. Substack's help centre says: 'We do not currently support Markdown in the post editor.' Some typing shortcuts work, such as ## for a heading, > for a quote and --- for a divider.
What's the fastest way to get an Obsidian note into Substack?
Render it (Obsidian's reading view or any Markdown preview), select and copy the rendered text, and paste into a Substack draft. Then drag your images in, and redo code, equations and tables with the editor's own blocks.
Can I import Markdown files into Substack?
Not as files. Substack's post importer reads URLs from listed platforms and RSS feeds. If your Markdown is published on your own site with an RSS feed, you can import from that feed.
Is there an API or CLI that posts Markdown to Substack?
There is no official one. Open-source CLIs exist, but they work by using your logged-in session, which Substack's terms restrict and which breaks when Substack changes its internals.
Can an AI assistant help?
Yes, for drafting and clean-up. An assistant can turn Markdown into paste-ready formatting or draft from your past posts. Substack's official MCP is read-only and cannot publish, so the final paste and publish stays with you.

Sources

  1. Substack help: Do you support Markdown? (accessed 2026-10-21)
  2. Substack help: Can I use shortcuts in the Substack editor? (accessed 2026-10-21)
  3. Substack help: How do I embed a code block in a Substack post? (accessed 2026-10-21)
  4. Substack help: How do I add equations to my Substack post? (accessed 2026-10-21)
  5. Substack help: How do I embed Datawrapper charts in a Substack post? (accessed 2026-10-21)
  6. Substack help: How do I embed media in my post (images, video, GIFs)? (accessed 2026-10-21)
  7. Substack help: Can I edit the CSS or HTML on Substack? (accessed 2026-10-21)
  8. Substack help: How can I edit images on a Substack post? (accessed 2026-10-21)
  9. Substack help: How can I add a template into my Substack post? (accessed 2026-10-21)
  10. Substack help: Why does it say 'Your post may be truncated'? (accessed 2026-10-21)
  11. Substack help: How do I import my posts from another platform? (accessed 2026-10-21)
  12. Substack help: If I import a post from elsewhere, will it be emailed out? (accessed 2026-10-21)
  13. Substack help: How to connect Substack to your AI Assistant (accessed 2026-10-21)
  14. Substack Terms of Use (accessed 2026-10-21)
  15. Reddit r/ObsidianMD: copy-pasting Obsidian notes into Substack (accessed 2026-10-21)
  16. Hacker News: copy-paste is the universal API (accessed 2026-10-21)

Related guides