TryGhost · PaulAdamDavis · Oct 5, 2020
diff --git a/README.md b/README.md
@@ -1,62 +1,65 @@
 # 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`
 
 ## Usage
 
 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/<your-username>/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 <package name>`
 
+1. Install [slimer](https://github.com/TryGhost/slimer)
+2. Run `slimer new <package name>`
 
-## 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
@@ -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
@@ -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
@@ -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: '<h2>Good stuff here</h2>'
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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).