Export content using the WordPress JSON API, and generate a zip
file you can import into a Ghost installation.
To install the CLI, which is required for the Usage commands below:
npm install --global @tryghost/migrate
To use this package in your own project:
npm install @tryghost/mg-wp-api --save
or
yarn add @tryghost/mg-wp-api
To run an absolute basic WordPress migration, the required command is this:
migrate wp-api --url https://example.com
It's possible to pass more options, in order to achieve a better migration file for Ghost:
-
--url
(required)- Path to a WordPress site
- string - default:
false
-
-V
--verbose
- Show verbose output
- bool - default:
false
-
--zip
- Create a zip file
- bool - default:
true
-
--onlyURLs
- Path to a CSV file of post URLs that will be the only migrated posts
- string - default:
null
-
-s
--scrape
- Configure scraping tasks
- string - default:
all
- Choices:
all
,img
,web
,media
,files
,none
-
--sizeLimit
- number - default:
false
- Media files larger than this size (defined in MB [i.e.
5
]) will be flagged as oversize
- number - default:
-
-I
--info
- bool - default:
false
- Show initalisation info only
- bool - default:
-
-b
--batch
- number - default:
0
- Batch number to run (defaults to running all)
- number - default:
-
-l
--limit
- number - default:
15
- Number of items fetched in a batch i.e. batch size
- number - default:
-
-a
--auth
- string - default:
null
- Provide a user and password to authenticate the WordPress API (:)
- string - default:
-
-u
--users
- string - default:
null
- Provide a JSON file with users. Contents should be a JSON array of objects that match the format returned by the Wordpress API, including the following keys: "id", "slug", "name", "description", "email" and "url".
- string - default:
-
--posts**
- boolean - default:
true
- Import posts
- boolean - default:
-
--pages**
- boolean - default:
true
- Import pages
- boolean - default:
-
--tags
- boolean - default:
true
- Set to false if you don't want to import WordPress tags, only categories
- boolean - default:
-
--addTag
- string - default:
null
- Provide a tag slug which should be added to every post in this migration
- string - default:
-
--featureImage
- Change which value is used as the feature image
- string - default:
featuredmedia
- Choices:
featuredmedia
,og:image
,none
-
--excerpt
- bool - default:
true
- Use the excerpt value from WordPress API
- bool - default:
-
--excerptSelector
- string - default:
null
- Pass in a valid selector to grab a custom excerpt from the post content, e. g.
h2.excerpt
- string - default:
-
--datedPermalinks
- Set the dated permalink structure.
/*/
matches any prefix, such as/articles/2018/05/
or/blog-posts/2018/05/
- string - default:
none
- Choices:
none
,'/yyyy/mm/'
,'/yyyy/mm/dd/'
,'/*/yyyy/mm/'
,'/*/yyyy/mm/dd/'
- NOTE: When using
/*/
, this is only to match existing links. Fixed links will not contain this.
- Set the dated permalink structure.
-
--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
-
--cpt
- A comma-separated list of custom post type slugs e.g.
resources,newsletters
- array - default:
null
- A comma-separated list of custom post type slugs e.g.
-
--fallBackHTMLCard
- Fall back to convert to HTMLCard, if standard Mobiledoc convert fails
- bool - default:
true
-
--removeSelectors
Pass in a string of CSS selectors for elements that will be removed, e.g. '.ads, script[src*="adnetwork.com"]'
- string - default:
null
-
--trustSelfSignedCert
- Trust self-signed certificates (such as for local installs)
- bool - default:
false
-
--cache
- Persist local cache after migration is complete (Only if
--zip
istrue
) - bool - default:
true
- Persist local cache after migration is complete (Only if
A more realistic command for a WordPress migration looks like this:
migrate wp-api --url https://example.com --auth person:pa55w0rd --addTag 'From old site' --limit 10 --batch 5
This will fetch the newest 50 posts, in 5 batches of 10, collect real author data including email addresses), and add the tag 'From old site'.
migrate wp-api --url https://example.com --scrape img web
This will fetch all posts, and only scrape image & web meta data
migrate wp-api --url https://example.com --onlyURLs /path/to/urls.csv
The CSV should look like this:
url
https://example.com/2023/03/02/my-article
https://example.com/2023/03/01/another-article
This is a mono repository, managed with lerna.
Follow the instructions for the top-level repo.
-
git clone
this repo &cd
into it as usual - Run
yarn
to install top-level dependencies.
To run a local development copy, cd
into this directory, and use yarn dev
instead of migrate
like so:
yarn dev wp-api <url>
-
yarn lint
run just eslint -
yarn test
run lint and tests
Copyright (c) 2013-2023 Ghost Foundation - Released under the MIT license.