diff --git a/README.md b/README.md index 151a29f77..839d72cb1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Migrate -A collection of tools for migrating to Ghost +A collection of CLI tools for migrating to Ghost. ## Install -Migrate is a set of command line tools, install them globally: +Migrate is a set of command line tools. Install them globally to run a migration from anywhere: `npm install --global @tryghost/migrate` @@ -12,51 +12,54 @@ Migrate is a set of command line tools, install them globally: Run `migrate --help` to see a list of available commands. -Basic usage is `migrate [source] source-info`: +Basic usage follows this pattern: `migrate [source] [flags]` -E.g. +- `migrate medium path/to/export.zip` +- `migrate wp-api https://mywpsite.com` -`migrate medium path/to/export.zip` +Each tool comes with its own optional flags to customise the migration. +You can run `migrate [source] --help` to see these, or view the readme for each tool: -`migrate wp-api https://mywpsite.com` +- [HubSpot](https://github.com/TryGhost/migrate/tree/master/packages/mg-hubspot-api) +- [Medium](https://github.com/TryGhost/migrate/tree/master/packages/mg-medium-export) +- [Revue](https://github.com/TryGhost/migrate/tree/master/packages/mg-revue-api) +- [Squarespace](https://github.com/TryGhost/migrate/tree/master/packages/mg-squarespace-xml) +- [Substack](https://github.com/TryGhost/migrate/tree/master/packages/mg-substack-csv) +- [Substack members](https://github.com/TryGhost/migrate/tree/master/packages/mg-substack-members-csv) +- [WordPress](https://github.com/TryGhost/migrate/tree/master/packages/mg-wp-api) -Each source somes with optional flags to customise the migration: +## Developer Setup (for contributing) -`migrate [source] --help` will give more detail +This is a mono repository, managed with [lerna](https://lerna.js.org/). - -## Develop - -This is a mono repository, managed with [lerna](https://lernajs.io/). - -1. `git clone` this repo & `cd` into it as usual -2. `yarn setup` is mapped to `lerna bootstrap` - - installs all external dependencies - - links all internal dependencies +1. Fork this repo +2. `git clone https://github.com//migrate path/to/your/workspace` +3. `cd path/to/your/workspace` +4. `yarn setup` (mapped to `lerna bootstrap`) + - installs all external dependencies and links all internal dependencies To add a new package to the repo: - - install [slimer](https://github.com/TryGhost/slimer) - - run `slimer new ` +1. Install [slimer](https://github.com/TryGhost/slimer) +2. Run `slimer new ` -## Run +### Run -- `yarn dev` +```sh +yarn dev +``` +### Test -## Test +- `yarn lint` to run eslint only +- `yarn test` to run lint and tests -- `yarn lint` run just eslint -- `yarn test` run lint and tests - - -## Publish +### Publish - `yarn ship` is an alias for `lerna publish` - Publishes all packages which have changed - Also updates any packages which depend on changed packages - # Copyright & License Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). diff --git a/packages/listr-smart-renderer/README.md b/packages/listr-smart-renderer/README.md index f90619139..f042ca2db 100644 --- a/packages/listr-smart-renderer/README.md +++ b/packages/listr-smart-renderer/README.md @@ -7,7 +7,6 @@ The summary outputs one line for each task that is currently being executed, one Heavily based on [listr-update-renderer](https://github.com/SamVerschueren/listr-update-renderer), with all the same nice UI features. - ## Install `npm install @tryghost/listr-smart-renderer --save` @@ -19,7 +18,7 @@ or ## Usage -``` +```js const SmartRenderer = require('@tryghost/listr-smart-renderer'); const Listr = require('listr'); @@ -63,9 +62,9 @@ Clear the output when all the tasks are executed successfully. ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. @@ -82,4 +81,4 @@ Follow the instructions for the top-level repo. # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation, Sam Verschueren - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation, Sam Verschueren - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/listr-smart-renderer/LICENSE). diff --git a/packages/mg-fs-utils/README.md b/packages/mg-fs-utils/README.md index 37051657c..29e9e264e 100644 --- a/packages/mg-fs-utils/README.md +++ b/packages/mg-fs-utils/README.md @@ -1,5 +1,7 @@ # Migrate Fs Utils +A collection of utility used across various [migrate](https://github.com/TryGhost/migrate) packages. + ## Install `npm install @tryghost/mg-fs-utils --save` @@ -8,32 +10,36 @@ or `yarn add @tryghost/mg-fs-utils` - ## Usage +Usage is specific to each utility. It is recomended to require the tool you need, like the example below: + +```js +const csv = require('@tryghost/mg-fs-utils').csv; + +module.exports = async () => { + const input = await csv.parse('./path/to/file.csv'); + // do something with input +}; +``` ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-fs-utils/LICENSE). diff --git a/packages/mg-html-mobiledoc/README.md b/packages/mg-html-mobiledoc/README.md index a73dd4507..2bfd68f46 100644 --- a/packages/mg-html-mobiledoc/README.md +++ b/packages/mg-html-mobiledoc/README.md @@ -2,7 +2,6 @@ A little wrapper tool for migrating all HTML fields of posts to mobiledoc - ## Install `npm install @tryghost/mg-html-mobiledoc --save` @@ -11,18 +10,17 @@ or `yarn add @tryghost/mg-html-mobiledoc` - ## Usage ```js - var mgHtmlMobiledoc = require('tryghost/mg-html-mobiledoc'); - var convertedData = mgHtmlMobiledoc.convert(myData); +const mgHtmlMobiledoc = require('tryghost/mg-html-mobiledoc'); +const convertedData = mgHtmlMobiledoc.convert(myData); ``` -Data structure passed in can be either +The data structure passed into `convert` can be either: ```js -var myData = { +let myData = { posts: [ { html: '

Good stuff here

' @@ -34,7 +32,7 @@ var myData = { or ```js -var myData = { +let myData = { data: { posts: [ { @@ -45,27 +43,23 @@ var myData = { } ``` - ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-html-mobiledoc/LICENSE). diff --git a/packages/mg-hubspot-api/README.md b/packages/mg-hubspot-api/README.md index 3c43ab1e0..cc6d0a4cb 100644 --- a/packages/mg-hubspot-api/README.md +++ b/packages/mg-hubspot-api/README.md @@ -8,32 +8,26 @@ or `yarn add @tryghost/mg-hubspot-api` - ## Usage ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-hubspot-api/LICENSE). diff --git a/packages/mg-imagescraper/README.md b/packages/mg-imagescraper/README.md index 9f37a98b1..b781af737 100644 --- a/packages/mg-imagescraper/README.md +++ b/packages/mg-imagescraper/README.md @@ -8,32 +8,26 @@ or `yarn add @tryghost/mg-imagescraper` - ## Usage ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-imagescraper/LICENSE). diff --git a/packages/mg-json/README.md b/packages/mg-json/README.md index 009ce9a1d..7f0a4dc20 100644 --- a/packages/mg-json/README.md +++ b/packages/mg-json/README.md @@ -10,30 +10,26 @@ or `yarn add @tryghost/mg-json` - ## Usage ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-json/LICENSE). diff --git a/packages/mg-linkfixer/README.md b/packages/mg-linkfixer/README.md index 7ccf5ba02..e14de92fa 100644 --- a/packages/mg-linkfixer/README.md +++ b/packages/mg-linkfixer/README.md @@ -8,32 +8,26 @@ or `yarn add @tryghost/mg-linkfixer` - ## Usage ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-linkfixer/LICENSE). diff --git a/packages/mg-medium-export/README.md b/packages/mg-medium-export/README.md index f03e9d068..0fd8c2e3e 100644 --- a/packages/mg-medium-export/README.md +++ b/packages/mg-medium-export/README.md @@ -1,5 +1,7 @@ # Migrate Medium Export +This tool uses the zip file Medium that provides, and creates a zip file ready to import into Ghost. That zip file contains a `json` file and a folder of images. + ## Install `npm install @tryghost/mg-medium-export --save` @@ -8,32 +10,59 @@ or `yarn add @tryghost/mg-medium-export` - ## Usage +To run a Medium migration, the required command is: + +```sh +migrate medium the-export-file.zip +``` + +It's possible to pass more options, in order to achieve a better migration file for Ghost: + +- **`-V` `--verbose`** + - bool - default: `false` + - Show verbose output +- **`--zip`** + - bool - default: `true` + - Create a zip file +- **`-s` `--scrape`** + - string - default: `all` + - Configure scraping tasks (choices: `all`, `web`, `img`, `none`) +- **`-e` `--email`** + - bool/string - default: `false` + - Provide an email domain for users e.g. `mycompany.com` +- **`--fallBackHTMLCard`** + - bool - default: `false` + - Fall back to convert to HTMLCard, if standard Mobiledoc convert fails + +A more complex migration command could look like this: + +```sh +migrate medium the-export-file.zip --email mycompany.com --fallBackHTMLCard true --verbose +``` ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. +### Run -## Run - -- `yarn dev` +To run a local development copy, `cd` into this directory, and replace `migrate` with `yarn dev`, like so: +```sh +yarn dev medium path/to/the-export-file.zip +``` -## Test +### Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-medium-export/LICENSE). diff --git a/packages/mg-revue-api/README.md b/packages/mg-revue-api/README.md index aeba8d17a..49958424d 100644 --- a/packages/mg-revue-api/README.md +++ b/packages/mg-revue-api/README.md @@ -1,5 +1,7 @@ # Migrate Revue Api +This tool requests data from the Revue API, and creates a zip file ready to import into Ghost. That zip file contains a `json` file and a folder of images. + ## Install `npm install @tryghost/mg-revue-api --save` @@ -8,7 +10,6 @@ or `yarn add @tryghost/mg-revue-api` - ## Usage Revue has and API that we can use to fetch content for migration. The token can be found on the [integrations page](https://www.getrevue.co/app/integrations) when logged in. @@ -21,44 +22,55 @@ The `pubName` value is the publication or user name. It's the last part of the p It's possible to pass more options, in order to achieve a better migration file for Ghost: -`--addPrimaryTag ` -Provide a tag slug or name which should be added to every post as primary tag. - -`--email ` -Provide an email or the author of the publication. - -`--fallBackHTMLCard false` -Fall back to convert to HTMLCard, if standard Mobiledoc convert fails - -
+- **`-V` `--verbose`** + - bool - default: `false` + - Show verbose output +- **`--zip`** + - bool - default: `true` + - Create a zip file +- **`-s` `--scrape`** + - string - default: `all` + - Configure scraping tasks (choices: `all`, `web`, `img`, `none`) +- **`--addPrimaryTag`** + - string - default: `null` + - Provide a tag name which should be added to every post as primary tag, such as `RevueImport` +- **`-e` `--email`** + - string - default: `null` + - Provide an email to create a general author for the posts, such as `john@mycompany.com` +- **`-I` `--info`** + - bool - default: `false` + - Show Revue API info only +- **`--fallBackHTMLCard`** + - bool - default: `false` + - Fall back to convert to HTMLCard, if standard Mobiledoc convert fails A more realistic command for a Substack migration looks like this: -`migrate revue --email ` - +```sh +migrate revue MyRevuePubName lz9scqda8fsy1rhw1ow7oz409jmpz8se --email john@mycompany.com --addPrimaryTag RevueImport +``` ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. +### Run -## Run - -- `yarn dev` +To run a local development copy, `cd` into this directory, and replace `migrate` with `yarn dev`, like so: +```sh +yarn dev revue MyRevuePubName lz9scqda8fsy1rhw1ow7oz409jmpz8se +``` -## Test +### Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2020 Ghost Foundation - Released under the [MIT license](LICENSE). \ No newline at end of file +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-revue-api/LICENSE). diff --git a/packages/mg-squarespace-xml/README.md b/packages/mg-squarespace-xml/README.md index d4b4fcaf1..d9a1bce34 100644 --- a/packages/mg-squarespace-xml/README.md +++ b/packages/mg-squarespace-xml/README.md @@ -1,4 +1,6 @@ -# Migrate Squarespace Xml +# Migrate Squarespace XML + +To migrate from Squrespace to Ghost, we use the WordPress export format Squarespace provides. The XML file is what we use as source material. ## Install @@ -8,55 +10,63 @@ or `yarn add @tryghost/mg-squarespace-xml` - ## Usage -Squarespace has a migration path via WordPress which results in a `xml` with all content. - To run an absolute basic Squarespace migration, the required command is this: -`migrate squarespace ` +`migrate squarespace path/to/file.xml` It's possible to pass more options, in order to achieve a better migration file for Ghost: -`--drafts true` -You can decide to not import drafts, when the post was e. g. only used to generate a newsletter but never published as a post. In this case the newsletter would be classed as `draft` and you can decide to not import them by setting this flag to false - -`--pages false` -Squarespace, as a website builder, can contain more than just posts. By default, we're not importing pages. This flag can be set to `true` to change this setting. - -`--tags true` -Similar to WordPress, we have tags and categories. If you only want to import categories, set `tags` to `false` - -`--addTag ` -Provide an optional tag name that should be added to each migrated post/page. This will be **in addition** to the automatically generated internal tag `#sqs`. - -`--fallBackHTMLCard false` -Fall back to convert to HTMLCard, if standard Mobiledoc convert fails - +- **`-V` `--verbose`** + - bool - default: `false` + - Show verbose output +- **`--zip`** + - bool - default: `true` + - Create a zip file +- **`-s` `--scrape`** + - string - default: `all` + - Configure scraping tasks (choices: `all`, `web`, `img`, `none`) +- **`-e` `--email`** + - bool/string - default: `false` + - Provide an email domain for users e.g. `mycompany.com +- **`--drafts`** + - bool - default: `true` + - By default, we do include drafts in the import. If you used drafts to generate newsletters that were not published as posts, you can exclude them +- **`--pages`** + - bool - default: `false` + - Squarespace, as a website builder, can contain more than just posts. By default, we're not importing pages. Set this flag to `true` to import pages +- **`--tags`** + - bool - default: `true` + - Set to false if you don't want to import WordPress tags, only categories +- **`--addTag`** + - string - default: `null` + - Provide a tag slug which should be added to every post in this migration (`my-tag`). Additional tags will be *in addition* to the automatically applied internal tag `#sqs` +- **`--fallBackHTMLCard*`** + - bool - default: `false` + - Fall back to convert to HTMLCard, if standard Mobiledoc convert fails ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run -- `yarn dev` +To run a local development copy, `cd` into this directory, and replace `migrate` with `yarn dev`, like so: +```sh +yarn dev squarespace path/to/the-export-file.xml +``` ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2020 Ghost Foundation - Released under the [MIT license](LICENSE). \ No newline at end of file +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-squarespace-xml/LICENSE). diff --git a/packages/mg-substack-csv/README.md b/packages/mg-substack-csv/README.md index d8572272c..146924523 100644 --- a/packages/mg-substack-csv/README.md +++ b/packages/mg-substack-csv/README.md @@ -8,7 +8,6 @@ or `yarn add @tryghost/mg-substack-csv` - ## Usage Substack provides an overview `csv` file as well as a folder containing different files for each post. @@ -19,22 +18,30 @@ To run an absolute basic Substack migration, the required command is this: It's possible to pass more options, in order to achieve a better migration file for Ghost: -`--url ` -Provide a URL to the Substack instance, so we can try and scrape additional information for each post - -`--readPosts ` -Some Substack exports include a directory with `html` files for each post. - -`--email ` -Provide an email for users e.g. john@mycompany.com to create a general user w/ slug `john` and provided email - -`--drafts true` -You can decide to not import drafts, when the post was e. g. only used to generate a newsletter but never published as a post. In this case the newsletter would be classed as `draft` and you can decide to not import them by setting this flag to false - -`--fallBackHTMLCard false` -Fall back to convert to HTMLCard, if standard Mobiledoc convert fails - -
+- **`-V` `--verbose`** + - bool - default: `false` + - Show verbose output +- **`--zip`** + - bool - default: `true` + - Create a zip file +- **`-s` `--scrape`** + - string - default: `all` + - Configure scraping tasks (choices: `all`, `web`, `img`, `none`) +- **`-e` `--email`** + - bool/string - default: `false` + - Provide an email domain for users e.g. `mycompany.com` +- **`-u` `--url`** + - string - default:`https://ghost.io` + - Provide a URL (without trailing slash) to the hosted source site, so we can scrape data +- **`-p` `--readPosts`** + - string - default: `null` + - Provide a path to a posts folder that contains HTML files (file name = post id) to read the post content +- **`--drafts`** + - bool - default: `true` + - Import draft posts +- **`--fallBackHTMLCard`** + - bool - default: `false` + - Fall back to convert to HTMLCard, if standard Mobiledoc convert fails A more realistic command for a Substack migration looks like this: @@ -42,26 +49,25 @@ A more realistic command for a Substack migration looks like this: ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. +### Run -## Run - -- `yarn dev` +To run a local development copy, `cd` into this directory, and replace `migrate` with `yarn dev`, like so: +```sh +yarn dev substack path/to/posts.csv +``` ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-substack-csv/LICENSE). diff --git a/packages/mg-substack-members-csv/README.md b/packages/mg-substack-members-csv/README.md index 3471d7a23..671afb6ea 100644 --- a/packages/mg-substack-members-csv/README.md +++ b/packages/mg-substack-members-csv/README.md @@ -1,6 +1,6 @@ # Substack Ghost Csv Converter -Allows converting CSV export from Substack to CSV compatible with Ghost. +Converts the CSV export from Substack to a CSV compatible with Ghost. ## Install @@ -10,33 +10,79 @@ or `yarn add @tryghost/mg-substack-members-csv` - ## Usage -To convert the CSV file provide a path to in as a first parameter and the output csv file path as second parameter: `subghost ` +To run a Substack CSV migration, the required command is: + +```sh +migrate substack-members path/to/emails.csv +``` + +To convert paid subscriptions, add `--subs` with a second file path: + +```sh +migrate substack-members path/to/emails.csv --subs path/to/members.csv +``` + +It's possible to pass more options, in order to achieve a better migration file for Ghost: + +- **`-V` `--verbose`** + - bool - default: `false` + - Show verbose output +- **`-s` `--subs`** + - string - default: `null` + - Path to the subscribers CSV file (paid, comp, gift) as generated by Substack ("Subscribers") +- **`-l` `--limit`** + - int - default: `6000` + - Define the batch limit for import files +- **`--comp`** + - string - default: `10` + - choices: `['none', 'free', 'number of years']` + - Decide what to do with subscribers on the `comp` plan. Provide a threshold number for lifelong complimentary plans. Subscribers with a `comp` plan above this threshold will get the lifelong complimentary plan +- **`--compLabel`** + - string - default: `substack-comp` + - Provide a label for Substack `comp` subscribers +- **`--gift`** + - string - default: `10` + - choices: `['none', 'free', 'number of years']` + - Decide what to do with subscribers on the `gift` plan. Provide a threshold number for lifelong complimentary plans. Subscribers with a `comp` plan above this threshold will get the lifelong complimentary plan +- **`--giftLabel`** + - string - default: `substack-gift` + - Provide a label for Substack `gift` subscribers +- **`--freeLabel`** + - string - default: `substack-free` + - Provide a label for Substack free subscribers +- **`--paidLabel`** + - string - default: `substack-paid` + - Provide a label for Substack paid subscribers + +A more complex migration command that accounts for Stripe data could look like this: + +```sh +migrate substack-members emails.csv --subs members.csv --giftLabel Gifted --freeLabel Free --paidLabel Supporter --compLabel Try\ It\ Out +``` ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. +### Run -## Run - -- `yarn dev` +To run a local development copy, `cd` into this directory, and replace `migrate` with `yarn dev`, like so: +```sh +yarn dev substack-members path/to/posts.csv +``` ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-substack-members/LICENSE). diff --git a/packages/mg-webscraper/README.md b/packages/mg-webscraper/README.md index 234518afd..7ce2b98c5 100644 --- a/packages/mg-webscraper/README.md +++ b/packages/mg-webscraper/README.md @@ -8,32 +8,26 @@ or `yarn add @tryghost/mg-webscraper` - ## Usage ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/tryghost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-webscraper/LICENSE). diff --git a/packages/mg-wp-api/README.md b/packages/mg-wp-api/README.md index ee01f8911..83f728cad 100644 --- a/packages/mg-wp-api/README.md +++ b/packages/mg-wp-api/README.md @@ -1,4 +1,6 @@ -# Migrate Wp Api +# Migrate WP Api + +This tool uses the [WordPress REST API](https://developer.wordpress.org/rest-api/) to fetch data, and creates a zip file ready to import into Ghost. That zip file contains a `json` file and a folder of images. ## Install @@ -8,32 +10,81 @@ or `yarn add @tryghost/mg-wp-api` - ## Usage +To run a WP migration, the required command is this: + +`migrate wp-api https://mywpsite.com` + +It's possible to pass more options, in order to achieve a better migration file for Ghost: + +- **`-V` `--verbose`** + - bool - default: `false` + - Show verbose output +- **`--zip`** + - bool - default: `true` + - Create a zip file +- **`-s` `--scrape`** + - string - default: `all` + - Configure scraping tasks (choices: `all`, `web`, `img`, `none`) +- **`-I` `--info`** + - bool - default: `false` + - Show initalisation info only +- **`-b` `--batch`** + - int - default: `0` + - Run a batch (defaults to not batching +- **`-l` `--limit`** + - int - default: `100` + - Number of items fetched in a batch i.e. batch size +- **`-a` `--auth`** + - string - default: `null` + - Provide a user and password to authenticate the WordPress API (`:`) +- **`-u` `--users`** + - string - default: `null` + - Provide a JSON file with users +- **`--tags`** + - bool - default: `true` + - Set to false if you don't want to import WordPress tags, only categories +- **`--addTag`** + - string - default: `null` + - Provide a tag slug which should be added to every post in this migration (`my-tag`) +- **`--featureImage`** + - string - default: `featuredmedia` + - Change which value is used as the feature image (choices: `featuredmedia`, `og:image`, `none`) +- **`--excerptSelector`** + - string - default: `null` + - Pass in a valid selector to grab a custom excerpt from the post content, e. g. `h2.excerpt +- **`--fallBackHTMLCard`** + - bool - default: `false` + - Fall back to convert to HTMLCard, if standard Mobiledoc convert fails + +A more complex migration command could look like this: + +```sh +migrate wp-api https://mywpsite.com --limit 100 --addTag old-site --excerptSelector p.story-excerpt --fallBackHTMLCard true +``` ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. +### Run -## Run - -- `yarn dev` +To run a local development copy, `cd` into this directory, and replace `migrate` with `yarn dev`, like so: +```sh +yarn dev medium path/to/the-export-file.zip +``` -## Test +### Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2019 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/mg-wp-api/LICENSE). diff --git a/packages/migrate/README.md b/packages/migrate/README.md index d3d283884..85879247d 100644 --- a/packages/migrate/README.md +++ b/packages/migrate/README.md @@ -8,33 +8,27 @@ or `yarn global add @tryghost/migrate` - ## Usage `migrate medium ./path/to/medum-export.zip` ## Develop -This is a mono repository, managed with [lerna](https://lernajs.io/). +This is a mono repository, managed with [lerna](https://lerna.js.org/). -Follow the instructions for the top-level repo. +Follow the instructions for the [top-level repo](https://github.com/TryGhost/migrate). 1. `git clone` this repo & `cd` into it as usual 2. Run `yarn` to install top-level dependencies. - ## Run - `yarn dev` - ## Test - `yarn lint` run just eslint - `yarn test` run lint and tests - - - # Copyright & License -Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](LICENSE). +Copyright (c) 2013-2020 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/migrate/blob/master/packages/migrate/LICENSE).