# @tryghost/mg-substack

> Converts a Substack `zip` export and generates a `zip` file you can import into a Ghost installation.

Latest version **1.12.0** (published 2026-08-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @tryghost/mg-substack
pnpm add @tryghost/mg-substack
yarn add @tryghost/mg-substack
bun add @tryghost/mg-substack
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.12.0 |
| Published | 2026-08-24 |
| First published | 2022-09-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 10 |
| Unpacked size | 46.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 69 |
| Author | Ghost Foundation |
| Maintainers | zimoatghost, allouis, kernalghost, chrisraible, erisds, johnonolan, kevinansfield, cobbspur, aileencgn, jloh, minimaluminium, sam-lord, pauladamdavis, bobvaneck, joeegrigg, hadret, erik-ghost, sagzy, vershwal, zach1618, mike182uk, luissazevedo, lsinger, nickmoreton, renatoworks, rblstr-ghost, evanhahn-ghost, austin.burdine, weylandswart, ghost-slimer, tmciesco, jonatan-ghost, 9larsons |

## Links

- npm: https://www.npmjs.com/package/@tryghost/mg-substack
- Repository: https://github.com/TryGhost/migrate
- Homepage: https://github.com/TryGhost/migrate#readme
- Issues: https://github.com/TryGhost/migrate/issues
- npm.io page: https://npm.io/package/@tryghost/mg-substack

## Dependencies (10)

- [he](https://npm.io/package/he.md) 1.2.0
- [srcset](https://npm.io/package/srcset.md) 5.0.3
- [simple-dom](https://npm.io/package/simple-dom.md) 1.4.0
- [html-entities](https://npm.io/package/html-entities.md) 2.6.0
- [@tryghost/debug](https://npm.io/package/@tryghost/debug.md) 2.3.6
- [@tryghost/errors](https://npm.io/package/@tryghost/errors.md) 3.3.6
- [@tryghost/string](https://npm.io/package/@tryghost/string.md) 0.3.5
- [@tryghost/mg-utils](https://npm.io/package/@tryghost/mg-utils.md) 0.11.6
- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) 5.0.0
- [@tryghost/mg-fs-utils](https://npm.io/package/@tryghost/mg-fs-utils.md) 0.26.6

## Recent versions

- 1.12.0 (latest) — 2026-08-24
- 1.11.0 — 2026-08-19
- 1.10.0 — 2026-08-12
- 1.9.0 — 2026-08-04
- 1.8.0 — 2026-07-15
- 1.7.0 — 2026-07-01
- 1.6.0 — 2026-06-17
- 1.5.0 — 2026-06-04
- 1.4.0 — 2026-05-07
- 1.3.3 — 2026-04-28
- 1.3.2 — 2026-04-28
- 1.3.1 — 2026-04-24
- 1.3.0 — 2026-04-20
- 1.2.0 — 2026-04-16
- 1.1.0 — 2026-04-10
- … 86 more at https://npm.io/package/@tryghost/mg-substack/versions

## README

# Migrate Substack `zip` Export

Converts a Substack `zip` export and generates a `zip` file you can import into a Ghost installation.


## Install

To install the CLI, which is required for the Usage commands below:

```sh
npm install --global @tryghost/migrate
```

To use this package in your own project:

`npm install @tryghost/mg-substack --save`

or

`pnpm add @tryghost/mg-substack`


## Usage

To run basic Substack migration, the required command is this:

```sh
migrate substack --pathToZip /path/to/my-export.zip --url https://example.com
```

A more complex command for a Substack migration looks like this:

```sh
migrate substack --pathToZip /path/to/my-export.zip --url https://example.com --email 'person@example.com' --drafts false
```

```sh
migrate substack --pathToZip /path/to/my-export.zip --url https://example.com --posts false --pages false --podcasts false --threads true
```

It's possible to pass more options, in order to achieve a better migration file for Ghost:

- **`--pathToZip`** (required)
    - Path to a zip file
    - string - default: `null`
- **`--url`** (required)
    - Site URL
    - string - default: `null`  
- **`-V` `--verbose`** 
    - Show verbose output
    - bool - default: `false`
- **`--zip`** 
    - Create a zip file
    - bool - default: `true`
- **`-s` `--scrape`** 
    - Configure scraping tasks
    - string - default: `all` 
    - Choices: `all`, `web`, `assets`, `none`
        - `all`: Scrape web metadata and download assets
        - `web`: Only scrape metadata from web pages
        - `assets`: Only download assets (images, media, files)
        - `none`: Skip all scraping tasks
- **`-e` `--email`** 
    - Provide an email domain for users e.g. `person@example.com` (Is ignored if `--useMetaAuthor` is provided)
    - bool/string - default: `false`
- **`--addTag`**
    - string - default: `null`
    - Provide a tag name which should be added to every post in this migration (Wrap in single quotes if tag name has spaces `'Like This'`)
- **`--addPlatformTag`** 
    - Add #substack tag to migrated content
    - bool - default: `true`
- **`--addTypeTag`** 
    - Add #substack-{type} tag to migrated content (post, podcast, etc)
    - bool - default: `true`
- **`--addAccessTag`** 
    - Add #substack-{access} tag to migrated content (public, paid, etc)
    - bool - default: `true`
- **`--posts`** 
    - Import posts
    - bool - default: `true`
- **`--drafts`** 
    - Import draft posts
    - bool - default: `true`
- **`--pages`** 
    - Import pages
    - bool - default: `true`
- **`--podcasts`** 
    - Import podcasts
    - bool - default: `true`
- **`--threads`** 
    - Import threads
    - bool - default: `false`
- **`--subscribeLink`** 
    - Provide a path that existing `/subscribe` anchors will link to e.g. `/join-us` or `#/portal/signup` (`#` characters need to be escaped with a `\`)
    - string - default: `#/portal/signup`
- **`--noSubscribeButtons`** 
    - Remove subscribe buttons and links from content (no replacement link)
    - bool - default: `false`
- **`--comments`** 
    - Keep comment buttons
    - bool - default: `true`
- **`--commentLink`** 
    - Provide a path that existing `/comments` anchors will link to e.g. `#ghost-comments-root` (`#` characters need to be escaped with a `\`)
    - string - default: `#ghost-comments-root`
- **`--useMetaImage`** 
    - Use `og:image` value as the feature image
    - bool - default: `true`  
- **`--useFirstImage`** 
    - Use the first image in content as the feature image (useMetaImage takes priority)
    - bool - default: `true`  
- **`--useMetaAuthor`** 
    - Use the author field from `ld+json` (useful for posts with multiple authors)
    - bool - default: `true`  
- **`--postsBefore`** 
    - Only migrate posts before and including a given date e.g. 'March 20 2018'
    - string - default: `null`
- **`--postsAfter`** 
    - Only migrate posts after and including a given date e.g. 'August 16 2023'
    - string - default: `null`
- **`--fallBackHTMLCard`** 
    - Fall back to convert to HTMLCard, if standard Mobiledoc convert fails
    - bool - default: `true`      
- **`--cache`** 
    - Persist local cache after migration is complete (Only if `--zip` is `true`)
    - bool - default: `true`

**Note**: You can combine `--postsBefore` and `--postsAfter` to migrate posts between 2 dates.


## Develop

This is a mono repository, managed with [Nx](https://nx.dev/) and pnpm workspaces.

Follow the instructions for the top-level repo.
1. `git clone` this repo & `cd` into it as usual
2. Run `pnpm install` to install top-level dependencies.


### Run

To run a local development copy, `cd` into this directory, and use `pnpm dev` instead of `migrate` like so:

```sh
pnpm dev substack <pathToZip>
```


## Test

- `pnpm test` runs the package tests
- Linting and formatting are run from the repo root (`pnpm lint`, `pnpm format`)


# Copyright & License

Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE).

---
_Source: https://npm.io/package/@tryghost/mg-substack · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._