From 6bd6a6565a72e7539270a839a22d945a35402925 Mon Sep 17 00:00:00 2001
From: August Miller <hello@gusmiller.com>
Date: Wed, 20 Nov 2024 10:51:28 -0800
Subject: [PATCH] Improvements to WordPress docs, recommend official tool

---
 docs/guides/migrating-from-wordpress.md | 54 +++++++++++++++++++++----
 1 file changed, 46 insertions(+), 8 deletions(-)

diff --git a/docs/guides/migrating-from-wordpress.md b/docs/guides/migrating-from-wordpress.md
index 3c2d0387..547a43c7 100644
--- a/docs/guides/migrating-from-wordpress.md
+++ b/docs/guides/migrating-from-wordpress.md
@@ -1,21 +1,59 @@
 # Migrating from WordPress
 
-Migrating from WordPress to Craft can be challenging, but we've found the process (in most cases) relatively straightforward. The challenge being simply getting your content out of WordPress due to plugins and other content-mashups.
+Migrating from WordPress to Craft can be challenging—but the bulk of the effort tends to be getting your content _out_ of WordPress (and various plugins’ content storage systems) and into a format that Feed Me understands.
 
-:::tip
-We are unable to offer any dedicated support for exporting out of WordPress. Its essentially up to you how you get your data, and this guide is for reference only.
+::: tip
+Consider reviewing the [updated recommendations](https://craftcms.com/knowledge-base/for-wordpress-devs) for Craft 5.x, which makes use of our new [dedicated import tool](https://github.com/craftcms/wp-import).
+
+While we are happy to support Feed Me and the `wp-import` extension, we are unable to offer help with third-party WordPress export tools. This guide provides some general recommendations, but may not be a turn-key solution for every WordPress installation!
 :::
 
 ### Create export from WordPress
 
-The first step is to get our data out of WordPress. In true, typical WordPress fashion—there's a plugin for that! Its called [WP All Export](https://en-au.wordpress.org/plugins/wp-all-export/), which you can download for free. It'll produce an XML file of your content and supports all native fields, Advanced Custom Fields, WooCommerce, Custom Taxonomies and Custom Post Types.
+The first step is to get our data out of WordPress. In our experience, the best community-maintained plugin is [WP All Export](https://en-au.wordpress.org/plugins/wp-all-export/), which you can download for free. It'll produce an XML file of your content and supports all native fields, Advanced Custom Fields, WooCommerce, Custom Taxonomies and Custom Post Types.
 
-:::tip
-We are not affiliated with the WordPress Export plugin—it’s simply the best tool we’ve come across.
+::: warning
+Make sure the WordPress `ID` is present for every record you export.
 :::
 
 We'll not be covering the ins-and-outs of how to export your content from WordPress—the plugin page above has an excellent video explaining it better than we can. Our recommendation is to essentially select every bit of data you can to export out, then setup Feed Me to import what you need.
 
-### Settings up Feed Me
+### Feed Me Settings
+
+Follow the guide to [Importing Entries](importing-entries.md), using the URL or file from the previous step. You may need to run multiple imports for different WordPress resources, mapped to the corresponding Craft element types—like _media_ ([assets](importing-assets.md)), _users_, and _taxonomies_.
+
+### How to Handle IDs
+
+When importing records from WordPress, they will receive new IDs. Create a custom field for legacy WordPress `ID`s and attach it to every import target (entry type, asset volume, etc.). When you set up your feed, map the WordPress ID to that custom field. This will help match up content if you need to re-import it again at a later date—and to connect things like posts and categories. 
+
+To illustrate, the WordPress post with `ID` `123`…
+
+```php{1}
+$post = get_post(123);
+get_the_title($post);
+// -> "Importing into Craft CMS" 
+```
+
+…will probably not end up with the same `id` in Craft…
+
+```twig{3}
+{% set post = craft.entries()
+  .section('posts')
+  .id(123)
+  .one() %}
+
+{{ post.title }}
+{# -> "How we use Advanced Custom Fields" 🚫 #}
+```
+
+By assigning the post `ID` to a custom field, you can look them up using the corresponding query method for the custom field:
+
+```twig{3}
+{% set post = craft.entries()
+  .section('posts')
+  .legacyWpId(123)
+  .one() %}
 
-Follow the guide to [Importing Entries](importing-entries.md), using the URL or file from the previous step.
+{{ post.title }}
+{# -> "Importing into Craft CMS" ✅ #}
+```