Docs: add docs about how to migrate to other domain/site or how to create a global redirect

[stsewd]

I've had a couple of requests about how to migrate a project to another domain/site.

Like if you want to change your project slug (old.rtd.io to new.rtd.io), or if you are migrating from rtd to another hosting provider (project.rtd.io to user.github.io/project/).

Each time I'll reply something like

You can create redirects to other sites, but redirects only work on 404s.
So in order to have a global redirect you can import an "empty" project (with only an index.rst file),
create an exact redirect from /$rest to https://new.readthedocs.io/ that would redirect any 404 like
https://old.readthedocs.io/en/latest/foo.html to https://new.readthedocs.io/en/latest/foo.html.
Additionally, you would also need to set a redirect in your index.rst manually by adding this content:

.. meta::
   :http-equiv=Refresh: 0; url='https://new.readthedocs.io/en/latest/'

This project has been moved, if you aren't redirected automatically
go to https://new.readthedocs.io/en/latest/.

I think it makes sense to have this documented in a guide, but I'm not sure about the content of the guide itself:

• How to migrate from rtd to another hosting provider (will cover how to redirect a full domain and other things, like if you are using a custom domain, you can just do the redirect by yourself)
• How to set a global redirect (will only cover how to redirect a full domain)

And, we could also create a "template project" where the user can just import that project and set an env variable with the new domain, create the exact redirect and be done with it.

[humitos]

We talked about this in #8143 as well. So, cross-linking it here.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[humitos]

I'm not a big fan of spending a lot of our time explaining to people the cleanest way to migrate out from our platform and then maintaining that guide over time. So, I'm fine closing this issue for now.

[palewire]

I can appreciate why it's not a priority, but this is an issue I run into from time to time. Personally, I'd love to see some clear, recommended solution. Ideally, I'd love for there to be a permanent redirect feature in the admin panel. If there's a way I could help either idea along please let me know. Thanks again for the great site.

[stsewd]

This is also useful for users that want to change their project slug, I don't think we should close this issue anyway.

[jaidisido]

In our case we are not leaving the ReadTheDocs platform. We simply wish to rename the url to a new one and have redirects in place. So we would appreciate if there is a clear guide on how to achieve this as the current one is incomplete/vague.

In case you are wondering why we wish to rename in the first place, that is because we plan to redirect our existing Github repository to a new Github organisation/repo name and therefore a new url would be required

[stsewd]

@jaidisido that's documented at https://docs.readthedocs.io/en/stable/user-defined-redirects.html#migrating-your-documentation-to-another-domain.

[jaidisido]

@stsewd, I have followed the instructions there and afaik they are incomplete. As you mention in your original comment, the user still has to follow a number of other steps such as creating an index.rst in a separate repository...

I've had a couple of requests about how to migrate a project to another domain/site.

Like if you want to change your project slug (old.rtd.io to new.rtd.io), or if you are migrating from rtd to another hosting provider (project.rtd.io to user.github.io/project/).

Each time I'll reply something like

You can create redirects to other sites, but redirects only work on 404s. So in order to have a global redirect you can import an "empty" project (with only an index.rst file), create an exact redirect from /$rest to https://new.readthedocs.io/ that would redirect any 404 like https://old.readthedocs.io/en/latest/foo.html to https://new.readthedocs.io/en/latest/foo.html. Additionally, you would also need to set a redirect in your index.rst manually by adding this content:

.. meta::
   :http-equiv=Refresh: 0; url='https://new.readthedocs.io/en/latest/'

This project has been moved, if you aren't redirected automatically
go to https://new.readthedocs.io/en/latest/.

I think it makes sense to have this documented in a guide, but I'm not sure about the content of the guide itself:

• How to migrate from rtd to another hosting provider (will cover how to redirect a full domain and other things, like if you are using a custom domain, you can just do the redirect by yourself)
• How to set a global redirect (will only cover how to redirect a full domain)

And, we could also create a "template project" where the user can just import that project and set an env variable with the new domain, create the exact redirect and be done with it.

[stsewd]

As you mention in your original comment, the user still has to follow a number of other steps such as creating an index.rst in a separate repository...

@jaidisido that's no longer a problem, we have "forced redirects", they work even if the page exists, to enable that feature you need to contact support at https://readthedocs.org/support/.