Obsidian to Substack: A Reliable Markdown Publishing Workflow

What transfers cleanly—and what needs attention

Prepare the Obsidian note for publication

1. 01

   Duplicate the note or use a publishing branch

   Do not flatten your working note just to satisfy a destination editor. Make a clean publication copy so vault links and research metadata remain intact in the original.

2. 02

   Choose the final title

   Add it as the only H1. Remove an Obsidian filename heading if it duplicates the same title, and make the first paragraph explain the reader benefit.

3. 03

   Expand transclusions

   Replace embedded notes, block references, and query results with the actual text a reader needs. A Substack subscriber cannot resolve paths inside your vault.

4. 04

   Convert links and callouts

   Turn wiki links into normal Markdown links with public destinations. Rewrite decorative callouts as headings, blockquotes, or plain paragraphs.

5. 05

   Inventory every image

   Locate the attachment behind each embed, give it a descriptive filename and alt text, and plan to upload it or include it as a generated publishing asset.

Move the cleaned note through StackDraft

Drag the cleaned .md file into StackDraft or paste its contents. Compare the preview with the reading view in Obsidian, but do not expect them to look identical: your Obsidian theme and snippets are intentionally not part of the portable document.

Work through the publishing checks from structural issues to cosmetic ones. Fix heading jumps and missing images first, then simplify wide tables and long code blocks. Mermaid blocks are rendered into static assets because JavaScript diagrams cannot run inside an email.

1. 01

   Copy title

   Paste the clean title into Substack’s dedicated title field.

2. 02

   Copy body

   Paste the rich body into the desktop post editor; the first H1 is removed from the body to prevent duplication.

3. 03

   Upload or confirm media

   Make sure every local attachment and generated asset is present in the Substack draft. Add alt text in Substack’s image menu.

4. 04

   Send a test

   Check a real email, not only the browser editor. Vault-based writing often contains the technical blocks most likely to stress an email layout.

Fix Obsidian image paths before they break

An Obsidian embed can refer to an attachment by filename because the vault indexes local files. A browser-based publishing destination cannot. Standard Markdown image syntax is more portable, but a relative path still points to your own folder unless the image is uploaded somewhere public.

Use meaningful alt text in the brackets. The alt text should convey the image’s function or insight, not repeat a caption word for word. After pasting, confirm or edit that description in Substack’s image controls.

Vault-only:
![[agent-loop.png]]

Portable Markdown source:
![Diagram showing the developer, model, tools, and review loop](https://example.com/agent-loop.png)

Use a repeatable publication template

A stable structure reduces last-minute formatting work without forcing every essay into the same voice. Substack also supports post templates on the web, so you can keep repeated publication-only elements—such as disclosures or subscription calls to action—on the destination side instead of in every Obsidian source note.

# {{title}}

One paragraph that states the reader's problem and promised outcome.

## Why this matters

Context and evidence.

## The workflow

1. Action
2. Action
3. Verification

## Common mistakes

- Mistake and fix
- Mistake and fix

## Takeaway

The decision or action the reader should remember.

Obsidian-to-Substack preflight checklist

• No frontmatter, dataview query, transclusion, block reference, or unresolved wiki link remains.
• The post has one H1 and a useful H2/H3 outline.
• Every local attachment has been uploaded or intentionally replaced.
• Tables are compact enough for a phone and summarized in prose.
• Mermaid diagrams are static images with readable labels.
• Code examples exclude secrets, private paths, and unnecessary output.
• The title and body were copied separately.
• A real test email passed link, image, and mobile checks.