Substack Export Import brings writer exports into your vault

Name: Substack Export Import
Author: theluckystrike

Import local Substack posts with properties.

Install in Obsidian

Directory page Source on GitHub

MIT · no telemetry · core features free

The export preview shows matched posts and one missing HTML body. — Open larger

version: 1.1.0
released: 2026-10-21
downloads: 19
review: Passed
health: Excellent
license: MIT
listed for: Desktop, Mobile
obsidian: 1.13.4 or later

The directory takes these platforms from the plugin manifest. The automated tests run in the desktop app only.

Directory facts fetched 2026-10-23 07:28 UTC from community.obsidian.md/users/theluckystrike.

About Substack Export Import

You want your Substack posts in your vault with publication fields and a report of missing bodies.

Select a local writer export ZIP and inspect its matched posts and missing bodies. The importer joins complete source IDs to HTML filenames and creates a new folder of Markdown notes. Subscriber data stays out of the import.

Preview a local writer export, read the report, and open an imported note

Free features

Preview a local export

Choose a ZIP with posts.csv at its root. The preview counts matched posts, missing bodies and HTML files without CSV rows. Read the report before creating notes.

The preview lists matched posts and a missing body. — Open larger

Convert post bodies to Markdown

The complete post_id must match posts/<post_id>.html. The importer converts cleaned HTML locally and uses the source ID as the note filename. It doesn't guess from titles or numeric prefixes.

An imported post shows a Markdown heading and body. — Open larger

Keep publication fields

Notes keep title, subtitle, post date, published state, audience, type and podcast URL. Published values become booleans when the CSV says true or false. Parseable dates also set file timestamps.

A podcast post keeps publication fields as note properties. — Open larger

Read the import report

The report lists missing HTML and orphan HTML paths without subscriber or delivery data. Rows without bodies don't create notes. Duplicate IDs stop preview before writing.

The report identifies missing bodies and HTML paths without CSV records. — Open larger

The core import and one-time property naming are free; saved profiles and body comparison need Pro.

Pro features

Pro costs $5 a month or $15 one time through GitHub Sponsors. One sponsorship turns on Pro in every plugin that has it.

Save field mappings and folder profiles Pro

Change property names for one import for free. Pro saves those names and a folder path as a profile. Load it later and choose a new output path.

Open larger

Compare later exports by post ID Pro

Compare Markdown bodies with the previous import's _substack-snapshot.json. Read changed bodies side by side without editing earlier notes. Property changes alone don't count as body changes.

Previous and new Markdown bodies appear beside each other. — Open larger

See how Pro works

Set up Substack Export Import

needs

Obsidian 1.13.4 or later
A local writer ZIP with posts.csv at its root.

steps

Keep the original ZIP and run Import writer export.
Enter a new output folder; a nested path needs an existing parent.
Select the local export and read its preview and report.
Select Create import folder, then inspect the new notes and report.

If the app can't find a new plugin yet, try again later. Obsidian says a plugin that passes the review shows in the app within 24 hours.

How to import a Substack writer export into Obsidian

Known limits of Substack Export Import

The ZIP must contain root posts.csv and direct posts/<post_id>.html files; wrapped exports are unsupported.
ZIP input is limited to 30 MiB, selected expanded text to 50 MiB, and archive members to 12,000.
Missing HTML produces no post note, and duplicate or conflicting IDs stop preview.
Images and podcast audio are not downloaded, and there is no podcast player.
Rendering an imported note can request remote images from their original hosts and disclose your network address.
Comparison detects Markdown body changes rather than property changes or edits to imported notes.
A failed disk write can leave a partial import in the new folder.
Current Substack account exports, physical mobile devices, Windows and Linux execution, large production archives and a live paid GitHub account were not tested.

Questions about Substack Export Import

Does this import subscribers or delivery statistics?

No. Those files are ignored, and their contents stay out of the report.

Are images and podcast audio downloaded?

No. Remote image URLs remain in Markdown, and podcast audio stays a URL property.

What changes does comparison detect?

It compares imported Markdown bodies by post ID. Property changes and your edits to previous vault notes don't count.

Network use

The plugin makes no requests before GitHub sign-in, which sends its client ID, read:user scope and polling requests to github.com. Authenticated checks send your token to api.github.com for sponsorship status without vault data; successful checks last seven days, and Refresh checks sooner. Import downloads no media, but rendering imported remote images can contact their original hosts and disclose your network address.

Read the full network disclosure