diff --git a/docs/assets/migration-aliasing.png b/docs/assets/migration-aliasing.png
new file mode 100644
index 000000000..2e1d89d82
Binary files /dev/null and b/docs/assets/migration-aliasing.png differ
diff --git a/docs/assets/migration-mastodon.png b/docs/assets/migration-mastodon.png
new file mode 100644
index 000000000..af899b4cf
Binary files /dev/null and b/docs/assets/migration-mastodon.png differ
diff --git a/docs/user_guide/migration.md b/docs/user_guide/migration.md
new file mode 100644
index 000000000..8d37a0869
--- /dev/null
+++ b/docs/user_guide/migration.md
@@ -0,0 +1,78 @@
+# Migration
+
+GoToSocial supports account migration using the `Move` activity.
+
+This allows you to move an account to your GoToSocial account, or to move your GoToSocial account to another account.
+
+Moving is software agnostic, so you can migrate your account to or from any software that supports the `Move` activity, regardless of the exact software. Eg., you can move your GoToSocial account to a Mastodon account, move your Mastodon account to a GoToSocial account, move your GoToSocial account to or from Akkoma, Misskey, GoToSocial, etc.
+
+!!! tip
+ Depending on the software that a target account is hosted on, target account URIs for both aliasing and moves should look something like `https://mastodon.example.org/users/account_you_are_moving_to`. If you are unsure what format to use, check with the admin of the instance you are moving or aliasing to.
+
+!!! warning
+ GoToSocial uses an account move cooldown of 7 days to prevent excessive instance hopping (and potential block evasion).
+
+ If either one of the accounts involved in a new move attempt have moved in the last seven days, GoToSocial will refuse to trigger a move to or from either account until seven days have passed since the previous move.
+
+## Move your GoToSocial account to another account (move *from* GoToSocial)
+
+Using the move account settings, you can trigger the migration of your GoToSocial account to the given target account URI.
+
+In order for the move to be successful:
+
+1. The target account (the account you are moving to) must be aliased back to your current account (the account you are moving from).
+2. The target account must be reachable from your current account, ie., not blocked by you, not blocking you, not suspended, not on a domain that is blocked by your current instance.
+
+Moving your account will send a message out from your current account, to your current followers, indicating that they should follow the target account instead. Depending on the server software used by your followers, they may then automatically send a follow (request) to the target account, and unfollow your current account.
+
+Currently, **only your followers will be carried over to the new account**. Other things like your following list, statuses, media, bookmarks, faves, blocks, etc, will not be carried over.
+
+Once your account has moved, the web view of your current (now old) account will show a notice that you have moved, and to where.
+
+Your old statuses and media will still be visible on the web view of the account you've moved from, unless you delete them manually. If you prefer, you can ask the admin of the instance you've moved from to suspend/delete your account after the move has gone through.
+
+If necessary, you can retry an account move using the same target account URI. This will send the move message out again. This is useful in cases where your followers may not have received the move message due to network issues or other temporary outage.
+
+!!! danger "Moving your account is an irreversible, permanent action!"
+
+ From the moment you trigger an account move from GoToSocial, you will have only basic read- and delete-level permissions on the account you've moved from.
+
+ You will still be able to log in to your old account and see your own posts, faves, bookmarks, blocks, and lists.
+
+ You will also be able to edit your profile, delete and/or unpin your own posts, and unboost, unfave, and unbookmark posts.
+
+ However, you will not be able to take any action that involves creating something, such as writing, boosting, bookmarking, or faving a post, following someone, uploading media, creating a list, etc.
+
+ Additionally, you will not be able to view any timelines (home, tag, public, list), or use the search functionality.
+
+## Move an account to your GoToSocial account (move *to* GoToSocial)
+
+To successfully trigger the migration of another account to your GoToSocial account, you must first create an **alias** linking your GoToSocial account back to the account you want to move from, to indicate to the account you're moving from that you also own the GoToSocial account you want to move to.
+
+To do this, you must first log in to the GoToSocial settings panel with your GoToSocial account. Eg., if your GoToSocial instance is at `https://example.org`, you should log in to the settings panel at `https://example.org/settings`.
+
+From there, go to the "Migration" section, and look at the "Alias Account" subsection:
+
+
+
+In the first free account alias box, enter the URL of the account you wish to move **from**. This indicates that the account you wish to move from belongs to you, ie., you are "also known as" the account.
+
+For example, if you are moving **from** the account "@dumpsterqueer" which is on the instance "ondergrond.org", you should enter the value "https://ondergrond.org/@dumpsterqueer" or "https://ondergrond.org/users/dumpsterqueer" as an account alias, as in the image above.
+
+Once you have entered your alias, click the "Save account aliases" button. If all goes well, a tick will be shown on the button. If not, an error will be shown which should help you figure out what went wrong.
+
+Once you have created the account alias from your GoToSocial account, pointing back to the account you wish to move **from**, you can use the settings panel on the other account's instance to trigger the move to your GoToSocial account.
+
+On Mastodon, the "Account migration" settings section looks something like this:
+
+
+
+If you were moving to a GoToSocial account from a Mastodon account, you would fill in the "Handle of the new account" field with the `@[username]@[domain]` value of your GoToSocial account. For example, if your GoToSocial account has username "@someone" and it's on the instance "example.org", you would enter `@someone@example.org` here.
+
+Once you have triggered the move from your other account to your GoToSocial account, the only thing you have left to do is accept follow requests from your old account's followers on your new (GoToSocial) account.
+
+!!! tip
+ To save yourself some trouble, consider setting your GoToSocial account to not require approval for new follow requests, just before triggering the migration. Once the migration is complete, turn approval of follow requests back on. Otherwise, you will have to manually approve every migrated follower from your old account.
+
+!!! warning
+ While the move will indicate to your followers that they should follow you at your GoToSocial account, GoToSocial does not yet support importing a list of accounts you follow. Until we implement this, you will have to manually follow accounts again from your GoToSocial account. Please see [this issue](https://github.com/superseriousbusiness/gotosocial/issues/1048) for more details.
diff --git a/docs/user_guide/settings.md b/docs/user_guide/settings.md
index 9cef48eff..52afb056f 100644
--- a/docs/user_guide/settings.md
+++ b/docs/user_guide/settings.md
@@ -201,47 +201,6 @@ For more information on the way GoToSocial manages passwords, please see the [Pa
## Migration
-In the migration section you can manage settings related to aliasing and/or migrating your account to another account.
+In the migration section you can manage settings related to aliasing and/or migrating your account to or from another account.
-!!! tip
- Depending on the software that a target account is hosted on, target account URIs for both aliasing and moves should look something like `https://mastodon.example.org/users/account_you_are_moving_to`. If you are unsure what format to use, check with the admin of the instance you are moving or aliasing to.
-
-### Alias Account
-
-You can use this section to create an alias from your GoToSocial account to other accounts elsewhere, indicating that you are also known as those accounts.
-
-**Not implemented yet**: Alias information for accounts you enter here will be shown on the web view of your profile, but only if the target accounts are also aliased back to your account first. This is to prevent accounts from claiming to be aliased to other accounts that they don't actually control.
-
-### Move Account
-
-Using the move account settings, you can trigger the migration of your current account to the given target account URI.
-
-In order for the move to be successful, the target account (the account you are moving to) must be aliased back to your current account (the account you are moving from). The target account must also be reachable from your current account, ie., not blocked by you, not suspended by your current instance, and not on a domain that is blocked by your current instance. The target account does not have to be on a GoToSocial instance.
-
-GoToSocial uses an account move cooldown of 7 days. If either your current account or the target account have recently been involved in a move, you will not be able to trigger a move to the target account until seven days have passed.
-
-Moving your account will send a message out from your current account, to your current followers, indicating that they should follow the target account instead. Depending on the server software used by your followers, they may then automatically send a follow (request) to the target account, and unfollow your current account.
-
-Currently, **only your followers will be carried over to the new account**. Other things like your following list, statuses, media, bookmarks, faves, blocks, etc, will not be carried over.
-
-Once your account has moved, the web view of your current (now old) account will show a notice that you have moved, and to where.
-
-Your old statuses and media will still be visible on the web view of the account you've moved from, unless you delete them manually. If you prefer, you can ask the admin of the instance you've moved from to suspend/delete your account after the move has gone through.
-
-If necessary, you can retry an account move using the same target account URI. This will send the move message out again.
-
-!!! danger "Moving your account is an irreversible, permanent action!"
-
- From the moment you trigger an account move, you will have only basic read- and delete-level permissions on the account you've moved from.
-
- You will still be able to log in to your old account and see your own posts, faves, bookmarks, blocks, and lists.
-
- You will also be able to edit your profile, delete and/or unpin your own posts, and unboost, unfave, and unbookmark posts.
-
- However, you will not be able to take any action that involves creating something, such as writing, boosting, bookmarking, or faving a post, following someone, uploading media, creating a list, etc.
-
- Additionally, you will not be able to view any timelines (home, tag, public, list), or use the search functionality.
-
-## Admins
-
-If your account has been promoted to admin, this interface will also show sections related to admin actions, see [Admin Settings](../admin/settings.md).
+Please see the [migration document](./migration.md) for more information on moving your account.
diff --git a/mkdocs.yml b/mkdocs.yml
index 61b997dae..a813ad132 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -67,6 +67,7 @@ nav:
- "user_guide/custom_css.md"
- "user_guide/password_management.md"
- "user_guide/rss.md"
+ - "user_guide/migration.md"
- "Getting Started":
- "getting_started/index.md"
- "getting_started/releases.md"
diff --git a/web/source/settings/views/user/migration.tsx b/web/source/settings/views/user/migration.tsx
index 5c964d457..4dc5d17c1 100644
--- a/web/source/settings/views/user/migration.tsx
+++ b/web/source/settings/views/user/migration.tsx
@@ -84,12 +84,12 @@ function AliasForm({ data: profile }) {
- Learn more about moving your account (opens in a new tab)
+ Learn more about account migration (opens in a new tab)