We’re moving to Read The Docs

oranod
Mon, 23 Jun 2025 18:38:11 +0000
Project Discussions

Hi everyone! The Ansible community team at Red Hat is excited to announce that we plan to migrate the docs.ansible.com subdomain to Read The Docs hosting.

This post explains our motivation and outlines our plan. Before we take action, we’d like to hear from you. Please give us your feedback by replying below. Questions are always welcome.

Summary: The hosting platform for Ansible community documentation is changing. There will be some changes to docs.ansible.com urls as a result but those changes should be transparent. Links will continue to work as they do today and you won’t need to update bookmarks. However you will likely notice that a /projects/ subdirectory appears in urls after the migration takes place.

Rationale for moving the subdomain

There are two main reasons behind this migration:

Improving the docs experience for the Ansible community (see more on this below).

Opening up the full release process to Ansible community maintainers. At the moment, only Red Hat employees can access the hosting infra for docs.ansible.com. Moving the subdomain to Read The Docs extends greater access to the Ansible package release process for the community.

Improving the docs experience

Going to docs.ansible.com today you’ll find documentation for the Ansible community package, ansible-core, and Ansible automation controller. To find documentation for other projects in the Ansible ecosystem, such as Ansible Lint or Ansible Builder, you need to visit ansible.readthedocs.io instead.

By migrating the subdomain to Read The Docs, we can have a unified space for all Ansible community documentation. We’ll also get some nice features like cross-project search, version switcher, and pull request previews.

All the Ansible community documentation is already available from ansible.readthedocs.io. Why not remove the subdomain and just use RTD?

We could do that, but the docs.ansible.com subdomain has a lot of SEO authority built up over time. When you search for “ansible”, the docs site is at the top of the list. By migrating the subdomain we ensure that authority stays with the Ansible community, where it belongs.

Additionally the docs.ansible.com subdomain signals the “official” location of trusted content for Ansible users, developers, maintainers, and contributors.

How does this affect me?

The answer to this question should be very little from a usability point of view. We’ve done a lot of work on our redirect strategy and will be reviewing and validating everything over the next couple of weeks before we start the migration process.

You do not need to update bookmarks or links to documentation in collection READMEs or other places where you might point to docs.ansible.com.

What you will notice is that there will be a /projects/ subdirectory in the urls for Ansible package documentation and ansible-core documentation, for example:

Ansible Documentation — Ansible Community Documentation

Ansible Core Documentation — Ansible Core Documentation

Read The Docs allows multiple docsites to be nested under a single namespace such as ansible.readthedocs.io. Each nested docsite is referred to as a subproject.

After the migration, the ansible.readthedocs.io subdomain will change to docs.ansible.com and the landing pages will be at the root level with each project, including core and the package, added as a subproject. After the change, you will have the following structure:

Landing pages: https://docs.ansible.com/

Ansible package: https://docs.ansible.com/projects/ansible/latest/

Ansible core: https://docs.ansible.com/projects/ansible-core/devel/

Ansible lint: https://docs.ansible.com/projects/lint/

We’ve already created redirects as outlined in Migrating docs to Read The Docs to handle the new URL structures and avoid breaking things. So, hopefully, our community will only be affected positively by having all the Ansible community docs in one place.

When will the migration take place?

We’re still gathering some details and lining things up for the move inside Red Hat. There are a couple of different teams involved and there’s still some coordination work to do. We don’t have set dates in the calendar but we do want to complete the migration soon.

However, there are distinct phases to this effort. We have this sequence of events in mind for the migration:

Socialize this post and gather feedback.

Complete migration phase one: Configure DNS entries and stand up the legacy-controller-docs.ansible.com subdomain.

Announce the new subdomain and give a week or two for community feedback.

Complete migration phase two: Move the CNAME record to Read The Docs hosting.

Complete migration phase three: Clean up work.

Call to action

We want to hear from you! Please give us your feedback! Here is how you can help:

Read our migration plan in the section below and reply to this post with your thoughts or comments.

Try out the Ansible package documentation and ansible-core documentation on Read The Docs. How does it compare to the corresponding page that is on docs.ansible.com today?

Check for broken links or 404 pages and help us test things. You’ll find lots of information in the plan and test details below.

If you find something that needs to be fixed, please open an issue in the ansible/ansible-documentation repository and add the rtd-migration label. We do welcome any contributions so if you see a change and open a pull request, feel free!

22 posts - 10 participants