To Substack

From an Obsidian note to a Substack draft or Note.

Write in Obsidian, choose your newsletter, and create a Substack draft with your title, subtitle, formatted text, and images. Or choose Note to publish directly to your Substack Notes feed. Your original note and attachments stay unchanged.

Install To Substack from Obsidian · Report an issue

Install To Substack

1. In Obsidian, open Settings → Community plugins → Browse.
2. Search for To Substack, then select Install and Enable.
3. Open Settings → To Substack to connect your account.

Requires Obsidian 1.14 or later and a Substack account. Newsletter drafts require access to a newsletter; publishing Notes does not.

The interface follows the language selected in Obsidian: English or French, with English used for other languages.

Connect your Substack account

1. Open Settings → To Substack and click Sign in.
2. Sign in on the Substack page that opens in a separate window. If Substack emails you a verification code, enter it in that same window.
3. Once your account is validated, the sign-in window closes automatically and your newsletters appear in the settings.

After checking your email, Return to sign-in brings the Substack window back to the front, including when it has been minimized. Cancel closes it and stops waiting for a connection.

Use Refresh to reload your newsletters, Switch account to connect another account, or Disconnect to remove the saved connection.

Create a draft from a note

1. Right-click a Markdown note in Obsidian's file explorer.
2. Choose To Substack.
3. Select the newsletter and click Create draft.
4. Follow Open draft in Substack to review your post.

Each export creates a new draft. You control publication and email delivery in Substack.

Under Settings → To Substack → Language editions, choose your notes' Default language, then check the other languages to add to Substack drafts. The default initially follows Obsidian's language when supported, or English otherwise. English, Spanish, German, Italian, European Portuguese, and French are supported; the other languages are initially checked. Uncheck every additional language to disable automatic editions. Your choices apply to future drafts.

If Additional post languages and Allow automatic translation are enabled in your Substack publication settings, To Substack prepares the selected editions. It skips the default language and the post's detected original language. Existing editions are preserved.

The plugin waits for Substack to generate the editions, then checks that they were saved before reporting them as ready. If a language cannot be confirmed, the draft link remains available so you can review the editions in Substack.

If the note has no level-one heading, its filename without .md becomes the title. The extracted title and opening italic paragraph are removed from the exported body. If there is no italic opening paragraph, the YAML metadescription property supplies the subtitle. Paragraphs, headings, bold, italics, web links, lists, blockquotes, inline code, code blocks, and horizontal rules keep their formatting.

For example:

# A walk by the river

*Notes from an autumn morning.*

The river was quiet. **The light changed everything.**

![[Photos/river.jpg]]

The draft is titled A walk by the river, with Notes from an autumn morning. as its subtitle. The body contains the paragraph and the photograph.

Include your images

Use Obsidian image embeds such as ![[photo.jpg]], Markdown images such as ![A view of the river](photo.jpg), or HTML <img> tags. Relative paths and filenames containing spaces are supported.

Local images are uploaded to the selected newsletter before the draft is created. Their position and alternative text are preserved, and a repeated image is uploaded once per draft. Images already hosted online keep their web address. The files in your vault are left intact.

If an image cannot be found or uploaded, the plugin stops before creating the draft and shows an error. If a connection error leaves the result of draft creation uncertain, check your Substack drafts before trying again.

Publish a Substack Note

1. Right-click a Markdown note and choose To Substack.
2. In Destination, select Note alongside your available newsletters.
3. Click Publish note. This publishes immediately to the connected account's Notes feed.
4. Follow Open note in Substack to view it.

To publish an excerpt, select text in the editor and choose To Substack from its context menu. Only Note is offered, and only the selected text and its images are sent. Without a selection, the destination chooser offers Note and your newsletters.

The title and opening italic paragraph remain in the Note's text. Headings become bold paragraphs; lists, quotes, links, and code retain their formatting. Images appear as gallery attachments, with a maximum of 20 unique images. Notes use Substack's own layout rather than inline image positions. Language edition settings apply to newsletter drafts.

If Substack does not confirm publication, check your Notes before trying again. The plugin never retries publication automatically.

Remove trailing tags

Enable Settings → To Substack → Export → Remove trailing tags to omit paragraphs containing only hashtags at the end of an article or Note. The option is off by default. Tags within the text and tags in code are preserved; your Obsidian file stays unchanged.

Account and privacy

Creating a draft or publishing a Note sends the selected content and images to Substack. Your session is kept in Obsidian's secret storage; the plugin settings contain only a reference to that secret.

Disconnecting removes the connection and clears the session secret created by To Substack. Secrets you imported from elsewhere remain available in Obsidian's secret storage.

Manual session setup

If the sign-in window is unavailable, open Manual connection → Substack session in the plugin settings. Choose or create a secret containing your substack.sid cookie value or the complete Cookie header from an authenticated Substack session, then click Refresh.

A session cookie grants access to your account. Keep it private.

Compatibility and limits

• The automatic sign-in window is available on desktop. Mobile requires manual session setup; the mobile workflow has not yet been validated on iOS or Android.
• Tables and embedded files other than images, including PDFs, audio, video, and embedded notes, are not supported.
• To Substack uses Substack's undocumented API. Changes to Substack may affect the connection, draft creation, or Note publication.

Questions or ideas?

Open an issue on GitHub with your Obsidian version, operating system, the error message, and a short example note. Remove session cookies and private information before sharing logs or screenshots.

To Substack is an independent, unofficial plugin by Thierry Crouzet.