# We’re moving to Read The Docs

**URL:** <https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519>\
**Category:** Project Discussions\
**Tags:** community, mindshare, community-wg-nextmtg, documentation, dawgs-meeting, ansible-lint\
**Created:** [June 23, 2025, 6:38pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519 "2025-06-23T18:38:11Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [June 23, 2025, 6:38pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/1 "2025-06-23T18:38:12Z")

</div>

Hi everyone! The Ansible community team at Red Hat is excited to announce that we plan to migrate the [docs.ansible.com](http://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](http://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](http://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](http://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](https://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](http://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](https://ansible.readthedocs.io/projects/ansible/latest/)
- [Ansible Core Documentation — Ansible Core Documentation](https://ansible.readthedocs.io/projects/ansible-core/devel/)

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](https://github.com/ansible/docsite) 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/](https://docs.ansible.com/projects/ansible/latest/)
- Ansible package:[https://docs.ansible.com/projects/ansible/latest/](https://docs.ansible.com/projects/ansible/latest/)
- Ansible core:[https://docs.ansible.com/projects/ansible-core/devel/](https://docs.ansible.com/projects/ansible-core/devel/)
- Ansible lint:[https://docs.ansible.com/projects/lint/](https://docs.ansible.com/projects/lint/)

We’ve already created redirects as outlined in[Migrating docs to Read The Docs](https://docs.readthedocs.io/en/stable/user-defined-redirects.html#migrating-your-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](http://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](https://ansible.readthedocs.io/projects/ansible/) and [ansible-core documentation](https://ansible.readthedocs.io/projects/ansible-core/) on Read The Docs. How does it compare to the corresponding page that is on [docs.ansible.com](http://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](https://github.com/ansible/ansible-documentation) repository and add the [rtd-migration](https://github.com/ansible/ansible-documentation/labels/rtd-migration) label. We do welcome any contributions so if you see a change and open a pull request, feel free!

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [June 23, 2025, 6:47pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/2 "2025-06-23T18:47:58Z")

</div>

# Preparing for a successful migration

Before we dive into the tasks involved in the migration plan, let’s go over some of the things we’ve been doing to get ready.

## Replacement subdomain for controller docs

As mentioned a bit earlier, there is some Automation controller documentation available from `docs.ansible.com`. That documentation is intended for Red Hat customers and is not moving to Read The Docs. We plan to keep the content on the web server after the migration is complete. For this reason, we need to create a new subdomain so folks can still find Automation controller documentation.

We’ve consulted the team responsible for that content and have decided to go with the `legacy-controller-docs.ansible.com` subdomain.

## Consolidating and converting redirects

To facilitate the migration to Read The Docs, we had to drastically reduce the number of server-side redirects. Read The Docs imposes a limit of 100 redirects per project. When we started out with the documentation for the Ansible community package, there were thousands of server-side redirects.

Earlier this year we [consolidated all the pre-collections redirects](https://forum.ansible.com/t/consolidating-redirects-on-docs-ansible-com/38897/). We also added an [Sphinx extension for redirects](https://github.com/ansible/ansible-documentation/pull/2418/) in the Ansible community docs.

As a result, we should not break any redirects in place for the Ansible community docs defined in the [top-level .htaccess file](https://raw.githubusercontent.com/ansible/docsite/refs/heads/main/.htaccess) or the [pre-collections redirects](https://raw.githubusercontent.com/ansible/docsite/576d5a6ed12d566cc9c13904dc179155b1ef4bfa/ansible/11/.htaccess).

# Phase one: Setting things up

Phase one of the migration sets up the `legacy-controller-docs.ansible.com` subdomain for Automation controller docs and adjusts DNS records.

## Creating a separate landing page

We need to create a landing page for the `legacy-controller-docs.ansible.com` subdomain that should:

- Briefly explain the migration to Read The Docs.
- Provide clear links to Ansible community and Ansible core documentation.
- Notify that Ansible core documentation from version 2.15 and later will be available from [docs.ansible.com](http://docs.ansible.com) after the migration.  
Note that we can enable builds for earlier versions in Read The Docs if necessary. It would be good to get feedback.
- Explain that we will not remove any pages from the current server but will no longer actively maintain or update them.  
For example, [Getting started with Ansible — Ansible Community Documentation](https://docs.ansible.com/ansible/11/getting_started/index.html) will still be available from the [legacy-controller-docs.ansible.com](http://legacy-controller-docs.ansible.com) subdomain.
- Provide entry points to the main pages that will be available after the migration, as follows:

```auto
ansible-tower.html
automation-tower-chinese-translations.html
automation-tower-japanese-translations.html
automation-tower-korean-translations.html
automation-tower-prior-versions.html
platform.html

```

To create the archive landing page, do the following:

1. Create an `archive-index.html` in the `ansible/docsite` repository.  
This index page should be as simple as possible and not generated from any template. It should use straightforward inline styling.
2. Update the `.htaccess` configuration to allow access to `archive-index.html`.
3. Update the docsite build job in Jenkins to deploy `archive-index.html` to the web server.

After migration, we will separate the index page from the `ansible/docsite` repository.

## Configuring DNS

Create a new LB record for `legacy-controller-docs.ansible.com` that points to the two servers and uses the same configuration as `docs.ansible.com`.

## Configuring the web server

We will serve `legacy-controller-docs` from the same server as `docs.ansible.com`.

1. Update the `roles/docs_and_release/tasks/main.yml` playbook to:

2. Configure the web server to handle requests for `legacy-controller-docs.ansible.com` by adding a new `VirtualHost` such as:

```auto
<VirtualHost *:80>
    ServerName legacy-controller-docs.ansible.com
    DocumentRoot /var/www/html/legacy-controller-docs/
    Options +Indexes
    <Directory /var/www/html/legacy-controller-docs/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride FileInfo Options=MultiViews
                Order allow,deny
                allow from all
    </Directory>
</VirtualHost>

```

## Setting things up on disc

1. Add a reference to the `ansible-tower` directory to the `index-archive.html` page.
2. Do a once off copy from `/var/www/html/docs/automation-controller ` AND `/var/www/html/docs/ansible-tower` to `/var/www/html/legacy-controller-docs`.
3. Move `/var/www/html/docs/index-archive.html` to `/var/www/html/legacy-controller-docs/index.html`
4. Copy landing pages into `/var/www/html/legacy-controller-docs`:

- `platform.html`
- `automation-tower-prior-versions.html`

1. Update controller jenkins jobs to rsync to the legacy-controller-docs folder instead of the docs folder.
2. Update the docsite jenkins job to remove the rsync for the `index-archive.html` file.

## Test plan for phase one

The archive subdomain, `legacy-controller-docs.ansible.com`, will be served from Red Hat managed infrastructure.

1. Use dig to verify DNS settings for `legacy-controller-docs.ansible.com` and `docs.ansible.com`.
2. Ensure that the archive landing page is available from `legacy-controller-docs.ansible.com`.
3. Ensure that entry points for legacy Automation Controller documentation is available from `legacy-controller-docs.ansible.com`.
4. Ensure that the docsite build job in Jenkins can update the archive landing page.

EDIT: I’ve updated plan details after working through a few changes. The original plan was based on more of a bottom up view that started from looking at what was on the server. After getting into some of the changes on cloudflare it made sense to take a slightly different approach and more cleanly separate things from the top-level down to disc.

EDIT2: Removed some of the steps from the test plan that no longer apply.

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [June 30, 2025, 5:56pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/3 "2025-06-30T17:56:33Z")

</div>

# Phase two: Migrating the subdomain

Update the CNAME record for [docs.ansible.com](http://docs.ansible.com) to point to Read The Docs.

1. Follow the steps to[add a custom domain on Read The Docs](https://docs.readthedocs.io/en/stable/guides/custom-domains.html#adding-a-custom-domain).  
a. Enter `docs.ansible.com` as the custom domain.  
b. Select the Canonical option.
2. Update the DNS record for `docs.ansible.com` so that it points to `readthedocs.io`.
3. Wait for the changes to propagate and then test with something like `nslookup` to verify the CNAME record.
4. Update the canonical url in `conf.py` to include the projects subdirectory: [ansible-documentation/docs/docsite/rst/conf.py at 350ef3df2c61dcce411f5c237ebc288079586003 · ansible/ansible-documentation · GitHub](https://github.com/ansible/ansible-documentation/blob/350ef3df2c61dcce411f5c237ebc288079586003/docs/docsite/rst/conf.py#L219)

## Test plan for phase two

After we add the `docs.ansible.com` subdomain to Read The Docs and update the DNS record, we should verify that changes have propagated as expected.

1. Check the canonical name that the subdomain points to: `nslookup -type=CNAME docs.ansible.com`
2. Check against Google’s DNS: `nslookup docs.ansible.com 8.8.8.8`
3. Check against Read The Doc’s name server: `nslookup docs.ansible.com tegan.ns.cloudflare.com`

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [June 30, 2025, 5:56pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/4 "2025-06-30T17:56:50Z")

</div>

# Phase three: Cleaning up

After the [docs.ansible.com](http://docs.ansible.com) subdomain is migrated to Read The Docs hosting, we should do some clean up work.

## Tasks in Google search console

To help preserve SEO authority of `docs.ansible.com`, we should perform the following steps in the search console:

- Verify both `docs.ansible.com` and the new subdomain are verified.
- Use the[Change of Address Tool](https://support.google.com/webmasters/answer/9370220?hl=en) to inform Google about the change of subdomain.
- Follow steps in[Move a site with URL changes](https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes) to monitor traffic and check for crawl errors.

## Custom sitemaps

XML sitemaps help search engines discover and index the site structure faster. Read The Docs automatically creates sitemaps, however we should consider generating a [custom sitemap](https://docs.readthedocs.io/en/stable/reference/sitemaps.html) for the top-level project.

Additionally, we should create a new XML sitemap for the new subdomain to replace the existing ones:

- [https://raw.githubusercontent.com/ansible/docsite/refs/heads/main/ansible-sitemap.xml](https://raw.githubusercontent.com/ansible/docsite/refs/heads/main/ansible-sitemap.xml)
- [https://github.com/ansible/docsite/blob/main/automation-controller-sitemap.xml](https://github.com/ansible/docsite/blob/main/automation-controller-sitemap.xml)

Here are some commands used to create sitemaps:

```auto
sudo dnf install nodejs
sudo npm install -g sitemap-generator-cli
sitemap-generator -f ansible-sitemap.xml https://docs.ansible.com/ansible/latest/
sitemap-generator -f automation-controller-sitemap.xml https://docs.ansible.com/automation-controller/latest/

```

## Custom robots.txt file

The `robots.txt file` helps improve SEO by controlling access to urls from search crawlers. We currently disallow several urls from search crawlers in [robots.txt](https://github.com/ansible/docsite/blob/main/robots.txt). We should investigate how to integrate that into the Sphinx configuration [according to their documentation](https://docs.readthedocs.com/platform/stable/reference/robots.html). Alternatively that might be something we just copy across in the Read The Docs configuration from the top-level domain.

## Updating internal links

Even though we will have redirects in place that should automatically point to the updated `docs.ansible.com` urls, we should ensure that as many links are updated as possible. Updating internal linking should help both users and search engines navigate the new structure without relying on redirects.

Here are some places where we should scan for `docs.ansible.com` urls and make batch updates where necessary:

- `ansible/ansible-documentation`
- `ansible/ansible`
- `ansible/aap-docs`

## Separating the landing pages

Landing pages refer to the top-level pages that guide users to relevant parts of the documentation.

After the migration, there will be two landing pages:

- `docs.ansible.com` on Read The Docs and sourced from the `ansible/docsite` repository
- `legacy-controller-docs.ansible.com` on the web server and sourced from the `legacy-controller-docs` folder in the `ansible/docsite` repository.

### Updating the landing page on Read The Docs

We should update the [docs.ansible.com](http://docs.ansible.com) landing pages to put the focus on the content journeys, which essentially means removing the following files and folders:

```auto
​​​├── ansible/
​​​├── templates/ansible_community.html
​​​├── templates/automation-tower-*.html
​​​├── templates/core-translated-ja.html
​​​├── templates/core.html
​​​├── templates/platform.html
​​​├── .htaccess
​​​├── ansible-sitemap.xml
​​​├── automation-controller-sitemap.xml
​​​└── robots.txt

```

1. Remove the preceding files and folders.
2. Update templates as appropriate to reflect the changes.
3. Update the `ecosystem.html` page to ensure links to Read The Docs projects are correct.
4. Ensure there is a link to the ecosystem page on the index.
5. Add redirects to the top-level Read The Docs project for the deleted `templates/*` pages.

As a future enhancement, we should consider building the [docs.ansible.com](http://docs.ansible.com) landing pages with Sphinx. This would allow us to make better use of the Read The Docs widget that provides cross-project search.

### Updating the prior versions page

We should ensure that the `templates/ansible-prior-versions.html` page has the correct urls for older versions of the Ansible community docs.

For instance, `https://docs.ansible.com/archive/ansible/2.7/` changes to `https://ansible.readthedocs.io/projects/ansible/2.7-archive/`

## Test plan for phase three clean up work

After the `docs.ansible.com` subdomain is transferred to Read The Docs hosting, additional testing is needed to ensure that pages are served correctly, redirects are working as expected, and that everything is in place.

1. Use curl to check and validate sitemaps.
2. Ensure that the landing pages for `docs.ansible.com` and `legacy-controller-docs.ansible.com` have the correct entry points and are clearly separated.

Edit: Removed some of the details about the landing page for `legacy-controller-docs.ansible.com`. We don’t need a separate repository for that. We’ll use bare bones [HTML files in a dedicated folder](https://github.com/ansible/docsite/tree/main/legacy-controller-docs) in the `ansible/docsite` repository instead.

---

<div class="post-metadata">

**Author:** ![utoddl](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/utoddl/32/249_2.png) [@utoddl](https://forum.ansible.com/u/utoddl)\
**Post date:** [June 30, 2025, 9:23pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/5 "2025-06-30T21:23:54Z")

</div>

Can’t see the garden for the weeds! Here’s a small thing (now), but still a thing.

> [@oranod](#):
>
> ```txt
> <VirtualHost *:80>
> ServerName legacy-controller-docs.ansible.com
> DocumentRoot /var/www/html/legacy-controller-docs/
> Options +Indexes
> <Directory /var/www/html/legacy-controller-docs/>
> Options Indexes FollowSymLinks MultiViews
> AllowOverride FileInfo Options=MultiViews
> Order allow,deny
> allow from all
> </Directory>
> </VirtualHost>
> 
> ```

Apache httpd 2.4 [docs](https://httpd.apache.org/docs/2.4/howto/access.html) warn

> The [`Allow`](https://httpd.apache.org/docs/2.4/mod/mod_access_compat.html#allow), [`Deny`](https://httpd.apache.org/docs/2.4/mod/mod_access_compat.html#deny), and [`Order`](https://httpd.apache.org/docs/2.4/mod/mod_access_compat.html#order) directives, provided by [`mod_access_compat`](https://httpd.apache.org/docs/2.4/mod/mod_access_compat.html), are deprecated and will go away in a future version. You should avoid using them, and avoid outdated tutorials recommending their use.

The effective equivalent using [`mod_authz_host`](https://httpd.apache.org/docs/2.4/mod/mod_authz_host.html) is

```auto
Require all granted

```

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [July 7, 2025, 1:50pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/6 "2025-07-07T13:50:09Z")

</div>

> [@utoddl](#):
>
> a future version. You should avoid using them, and avoid outdated tutorials recommending their use.

Thanks a mill for calling this out @utoddl

Here is the updated config with the `Require` directive:

```auto
<VirtualHost *:80>
    ServerName legacy-controller-docs.ansible.com
    ServerAlias legacy-controller-docs.ansible.com
    DocumentRoot /var/www/html/legacy-controller-docs/
    Options +Indexes
    <Directory /var/www/html/legacy-controller-docs/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride FileInfo Options=MultiViews
                Require all granted
    </Directory>
</VirtualHost>

```

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [July 23, 2025, 4:15pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/7 "2025-07-23T16:15:30Z")

</div>

Hey everyone,

I’m pleased to say that we’ve completed phase one of the migration plan and [https://legacy-controller-docs.ansible.com/](https://legacy-controller-docs.ansible.com/) is now up and running.

Given August is PTO season we’ve decided to hold off on phase two of the plan until the end of August or early September.

Transferring the `docs.ansible.com` subdomain to Read The Docs is straightforward. But we want to make sure that folks are around and that we can get through all the clean up activities like updating sitemaps in a timely manner.

We’ve finally got the controller docs over to a new home and cleanly separated from Ansible community docs though. It’s really exciting to be this close!

See you again in a few weeks. 🏝 ☀

---

<div class="post-metadata">

**Author:** ![mariolenz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/mariolenz/32/108_2.png) [@mariolenz](https://forum.ansible.com/u/mariolenz)\
**Post date:** [September 4, 2025, 2:58pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/8 "2025-09-04T14:58:29Z")

</div>

FYI There are links to `docs.ansible.com` in the Ansible Community Package. I’ve cretaed [this issue](https://github.com/ansible-community/antsibull-build/issues/675) to ask if we should change this.

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [October 3, 2025, 4:03pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/9 "2025-10-03T16:03:59Z")

</div>

I’ve generated `.csv` and `.txt` reports that show the HTTP status codes for Ansible documentation.

The purpose of these reports is to validate the following before we migrate the `docs.ansible.com` subdomain to Read The Docs hosting:

- Read The Docs redirects are working correctly for the `projects/` subdirectory in urls. The expected HTTP status code is `301`.

- All Ansible community package and `ansible-core` documentation pages currently available from `docs.ansible.com` are available on `ansible.readthedocs.io`. The expected HTTP status code is `200`.

The reports are organized in the following folders:

`ansible_rtd_subproject_redirects`:

These reports check that pages with `ansible.readthedocs.io/ansible/` url structures redirect to the corresponding `ansible.readthedocs.io/projects/ansible/` urls.

`ansible_rtd_subproject_pages`:

These reports check that all Ansible community documentation pages are available.

Note that pages for 2.3 to 2.8 should redirect to latest and have HTTP status code `301`. Those versions are available from the [documentation archive page](https://ansible.readthedocs.io/ansible-prior-versions.html) but have different url slugs.

`core_rtd_subproject_redirects`:

These reports check that pages with `ansible.readthedocs.io/ansible-core/` url structures redirect to the corresponding `ansible.readthedocs.io/projects/ansible-core/` urls.

`core_rtd_subproject_pages`:

These reports check that all `ansible-core` documentation pages are available.

> For the `ansible-core` documentation I only generated url reports for `devel` and `stable-2.19` versions.

You can find the reports in a zip here: [https://github.com/user-attachments/files/22683999/doc-page-validation-reports.zip](https://github.com/user-attachments/files/22683999/doc-page-validation-reports.zip)

---

<div class="post-metadata">

**Author:** ![andygeorge](https://avatars.discourse-cdn.com/v4/letter/a/e68b1a/32.png) [@andygeorge](https://forum.ansible.com/u/andygeorge)\
**Post date:** [October 8, 2025, 8:51pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/10 "2025-10-08T20:51:12Z")

</div>

Is it intended that most links appear to be 404ing currently?

---

<div class="post-metadata">

**Author:** ![thedoc31](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/thedoc31/32/9611_2.png) [@thedoc31](https://forum.ansible.com/u/thedoc31)\
**Post date:** [October 8, 2025, 10:06pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/11 "2025-10-08T22:06:51Z")

</div>

Seeing the same thing. Links from the [docs.ansible.com](http://docs.ansible.com) homepage throw 404s.

I highly doubt that’s intentional. I wonder if they’re still pushing out 301 redirects or accidentally unpublished the current indexed pages before the 301s got pushed. Either way, the readthedocs links above do seem to work, but the search results there are not good. Trying to type “ansible.builtin.file” in the search box gives nothing useful. Have to drill down manually, assuming you know where to look.

@oranod@mariolenz please fix?

---

<div class="post-metadata">

**Author:** ![Leo](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/leo/32/23_2.png) [@Leo](https://forum.ansible.com/u/Leo)\
**Post date:** [October 8, 2025, 10:07pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/12 "2025-10-08T22:07:42Z")

</div>

Hello all, we are aware of the issue and it’s being looked into.

For this specific problem, please keep it to the related topic here: [Most links off of the docs.ansible.com site are currently 404ing - #2 by Leo](https://forum.ansible.com/t/most-links-off-of-the-docs-ansible-com-site-are-currently-404ing/44645/2)

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [October 8, 2025, 10:08pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/13 "2025-10-08T22:08:29Z")

</div>

Fix incoming. Something broke in the build pipeline. Sorry for the confusion. This only affects the “latest” docs which are the Ansible 12 docs here: [Ansible Documentation — Ansible Community Documentation](https://docs.ansible.com/ansible/12/index.html)

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [October 31, 2025, 1:57pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/14 "2025-10-31T13:57:17Z")

</div>

Hi all,

Finally getting ready to close this saga so heads up. @gundalow and I have booked ourselves some time on Monday, Nov 10. We’re planning to convert the A record for `docs.ansible.com` in cloudflare to a CNAME. Then we’ll point it to Read The Docs hosting.

If anyone has any cloudflare tips or tricks, I’d genuinely appreciate hearing them. Thanks!

---

<div class="post-metadata">

**Author:** ![briantist](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/briantist/32/130_2.png) [@briantist](https://forum.ansible.com/u/briantist)\
**Post date:** [October 31, 2025, 2:16pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/15 "2025-10-31T14:16:39Z")

</div>

> [@oranod](#):
>
> If anyone has any cloudflare tips or tricks, I’d genuinely appreciate hearing them. Thanks!

What kind of tips and tricks are you looking for?

Here’s one in case you didn’t know: CloudFlare supports “CNAME flattening” by the way, which lets you use a `CNAME` at the apex of a zone (which is usually not allowed), and they do that by resolving the `CNAME` into `A` / `AAAA` records that get returned by DNS.

I haven’t really been following this migration to RTD. Are you planning on having CF “proxy” to the RTD site?

This gives you features like having pages cached in CF’s CDN so that they can be returned faster and send less traffic to the backend (in this case to RTD). It can be especially useful for folks who might be far (routing wise) from RTD but closer to a CF CDN edge node.

It’s basically a toggle in the DNS to proxy through CF for a specific record, and the settings for caching, minifying, and all that can be set elsewhere like in page rules.

You can also exclude certain URLs from caching, or change their caching settings independently. From the CF console you can clear all or part of the cache, and turn on “development mode” for times when you’re rapidly changing the backend content and don’t want to be serving pages out of the cache.

Lots of cool stuff in there if you poke around.

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [October 31, 2025, 2:55pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/16 "2025-10-31T14:55:05Z")

</div>

Hey @briantist great to hear from you. Thanks for that response. Those are just the kind of tips and tricks I’d love to hear about.

> Are you planning on having CF “proxy” to the RTD site?

Right now it’s an A record but we’re planning to convert it to a CNAME and then point to `readthedocs.io` instead of the current load balancer. I don’t think we were planning to proxy through Cloudflare though because read the docs handles stuff like SSL and [uses cloudflare](https://docs.readthedocs.com/platform/stable/guides/custom-domains.html#adding-a-custom-domain). Essentially we’ll be using Cloudflare for DNS only.

Not sure if the CNAME flattening capability would apply here, even though I didn’t really know about that. The only change will be to the `docs.ansible.com` subdomain and `ansible.com` is the root domain / apex. Maybe I’m missing some nuances though?

I’m genuinely open to any and all input from folks in the community who have experience here. If you have any other specific questions or want to go through things in a bit more detail to offer advice, please let me know. And thanks again!

---

<div class="post-metadata">

**Author:** ![briantist](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/briantist/32/130_2.png) [@briantist](https://forum.ansible.com/u/briantist)\
**Post date:** [October 31, 2025, 3:40pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/17 "2025-10-31T15:40:47Z")

</div>

> [@oranod](#):
>
> Not sure if the CNAME flattening capability would apply here, even though I didn’t really know about that. The only change will be to the `docs.ansible.com` subdomain and `ansible.com` is the root domain / apex. Maybe I’m missing some nuances though?

If `docs.ansible.com` is a direct `A` record in a DNZ zone for `ansible.com` then you can use a `CNAME` to point `docs` elsewhere.

If `docs.ansible.com` is delegated (via setting `NS` records that point to cloudflare for example) and then CF is authoritative for the `docs.ansible.com` zone, then the apex of that zone is `docs.ansible.com` (it has its own `SOA` and everything) and you can’t use a `CNAME` in DNS proper at the root (apex) of it.

The technical reason is that a `CNAME` literally means to replace the entirety of that domain with another, which includes `SOA` and everything. In other words, if you have a `CNAME` for `a.b.example.com`, you cannot also have other record types in that same zone (like `MX` records for mail, `TXT` records, `SOA`, etc.).

But if CF is hosting the `docs.ansible.com` zone, you can set a `CNAME` there and it will automatically use flattening (there will be a little icon next to it telling you about it) and it will operate as `A` record(s). This works whether or not you proxy through them.

tl;dr: evrything will be fine either way I think 😛

---

<div class="post-metadata">

**Author:** ![gundalow](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/gundalow/32/99_2.png) [@gundalow](https://forum.ansible.com/u/gundalow)\
**Post date:** [October 31, 2025, 4:18pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/18 "2025-10-31T16:18:45Z")

</div>

Looking at the [Read the Docs CDN Page](https://docs.readthedocs.com/platform/latest/reference/cdn.html)

RTD used Cloudflare for both Community and RTD for business 🎉

Regarding cache refresh, [the RTD docs](https://docs.readthedocs.com/platform/latest/reference/cdn.html#automatic-cache-refresh) state:

> We automatically refresh the cache on the CDN when the following actions happen:
> 
> - Your project is saved.
> - Your domain is saved.
> - A new version of your documentation is built.
> 
> By refreshing the cache according to these rules, readers should **never see outdated content**. This makes the end-user experience seamless and fast.

---

<div class="post-metadata">

**Author:** ![dbrennand](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/dbrennand/32/7830_2.png) [@dbrennand](https://forum.ansible.com/u/dbrennand)\
**Post date:** [October 31, 2025, 4:45pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/19 "2025-10-31T16:45:02Z")

</div>

Hi @oranod

I think your approach sounds good. I use Cloudflare in a similar way for documentation which is located on GitHub Pages. Similarly to RTD, a CNAME record is required like:

```auto
Type: CNAME
Proxied: True
Name: homeops
Target: dbrennand.github.io

```

But in your case, RTD documentation [you linked earlier](https://docs.readthedocs.com/platform/stable/guides/custom-domains.html#adding-a-custom-domain) mentions specifically:

> **If you are using Cloudflare, make sure to disable the proxy status (orange cloud) for the CNAME record.**

Which makes sense as you said, RTD are using Cloudflare already so no need to enable the proxy (Orange Cloud) again for the CNAME record.

Hope the migration goes smooth 🙂

---

<div class="post-metadata">

**Author:** ![gundalow](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/gundalow/32/99_2.png) [@gundalow](https://forum.ansible.com/u/gundalow)\
**Post date:** [November 10, 2025, 10:58am UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/20 "2025-11-10T10:58:16Z")

</div>

Hi,  
🎉 Don and I updated DNS this morning. 🎉

We’ve got a few places we are still using the old URLs (ie `https://ansible.readthedocs.io/projects/navigator/`) which are correctly redirected, though we will tidy them up to point to `https://docs.ansible.com/projects/navigator/`

[Next page](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519.md?page=2)