# Creating redirects on Read The Docs

This document outlines a proposal to create redirects in the `ansible` project on Read The Docs. The `ansible` project is the top-level namespace for Ansible project documentation that includes the Ansible package docs, `ansible-core` docs, as well as docs for projects across the Ansible ecosystem.

The purpose of creating redirects in the `ansible` project on Read The Docs is to facilitate the migration of the `docs.ansible.com` subdomain from Red Hat managed infrastructure to Read the Docs hosting. By doing this we can prevent 404 errors that would cause SEO degradation.

## Redirects on Read The Docs

Read The Docs hosting provides a built-in redirect system that has a limit of 100 user-defined redirects on Read The Docs per project. For more details, refer to the [User Defined Redirects](https://docs.readthedocs.io/en/stable/user-defined-redirects.html) section of the Read The Docs documentation.

> To be equivalent to root pages on docs.ansible.com subdomain, the details in this plan concern redirects in the top-level `Ansible` project only.

There are approximately 30 redirects in this proposal to create in the `ansible` project on Read The Docs. At the moment, there are seven redirects that already exist in the project. This is well within the limit of 100 redirects and ensures we have enough capacity for additional redirects.

Once we create the redirects, the top-level project is not likely to change very often because it holds landing pages instead of project documentation. Therefore we will likely have less need for redirects in future. If more pages change in the Ansible package docs after we migrate everything over to Read The Docs, and we decide to create redirects to accompany those change, then we can add the redirects to the `package-doc-builds` project.

## Redirects for the projects subdirectory

Subprojects on Read The Docs include the `/projects/` subdirectory in the url. After the migration, this will change the url structure for pages in the Ansible package and Ansible core documentation, for example:

# Before migration
docs.ansible.com/ansible/latest/installation_guide/intro_installation.html

# After migration
docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html

To handle these new URL structures, we can create 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), as follows:

# Ansible package docs
Type: Exact Redirect
From URL: /ansible/*
To URL: /projects/ansible/:splat
Force Redirect: True

# Ansible core docs
Type: Exact Redirect
From URL: /ansible-core/*
To URL: /projects/ansible-core/:splat
Force Redirect: True

## Redirects for specific pages and subdirectories

There are several landing pages currently on `docs.ansible.com` that we will remove after the migration to Read The Docs. These mostly apply to old translations, automation controller content, and archived content that will not be recreated on Read The Docs.

The following redirects prevent 404s with landing pages that will no longer be available on `docs.ansible.com` after the migration:

# Core docs landing page
Type: Page Redirect
From URL: /core.html
To URL: /projects/ansible-core/:splat

# Japanese translations
Type: Page Redirect
From URL: /core-translated-ja.html
To URL: https://docs-archive.ansible.com/index.html

# Package docs archive
Type: Page Redirect
From URL: /ansible-prior-versions.html
To URL: https://docs-archive.ansible.com/index.html

The controller docs on `docs.ansible.com` have built up a lot of SEO authority. We want to preserve that and ensure that `docs.ansible.com/automation-controller` and `docs.ansible.com/ansible-tower/` pages do not 404. At the same time, we want controller docs on `docs.redhat.com` to eventually take priority over controller docs on the community site.

All controller content will stay on Red Hat managed infrastructure. We will not migrate Red Hat product content to Read The Docs or host it there. All Red Hat product content belongs on `redhat.com`.

The following redirects prevent 404s on `docs.ansible.com` from automation controller and platform content:

# Tower docs
Type: Exact Redirect
From URL: /ansible-tower/*
To URL: https://docs-archive.ansible.com/ansible-tower/:splat
Force Redirect: True

# Controller docs
Type: Exact Redirect
From URL: /automation-controller/*
To URL: https://docs-archive.ansible.com/automation-controller/:splat
Force Redirect: True

# Automation page
Type: Exact Redirect
From URL: /automation.html
To URL: https://docs-archive.ansible.com/index.html

# Platform page
Type: Exact Redirect
From URL: /platform.html
To URL: https://docs-archive.ansible.com/index.html

# Tower archive
Type: Exact Redirect
From URL: /automation-tower-prior-versions.html
To URL: https://docs-archive.ansible.com/index.html

# Chinese translations
Type: Exact Redirect
From URL: /automation-tower-chinese-translations.html
To URL: https://docs-archive.ansible.com/index.html

# Japanese translations
Type: Exact Redirect
From URL: /automation-tower-japanese-translations.html
To URL: https://docs-archive.ansible.com/index.html

# Korean translations
Type: Exact Redirect
From URL: /automation-tower-korean-translations.html
To URL: https://docs-archive.ansible.com/index.html

There were also some top-level pages and subdirectories on `docs.ansible.com` that were removed. Redirects were created for these pages in the `ansible/docsite` repository. After the migration, we should also add the following redirects to Read The Docs:

# Galaxy page
Type: Page Redirect
From URL: /galaxy.html
To URL: /projects/galaxy-ng/en/latest/index.html

# Lint page
Type: Page Redirect
From URL: /lint.html
To URL: /projects/lint/index.html

# Ansible-Lint directory
Type: Exact Redirect
From URL: /ansible-lint/*
To URL: /projects/lint/:splat
Force Redirect: True

## Consolidated redirects

As mentioned elsewhere, there are thousands of rules defined in multiple `.htaccess` configurations in the `ansible/docsite` repository. For maintenance reasons as well as to avoid exceeding the limit of 100 redirects for each Read The Docs project, we need to consolidate server-side redirects. For more information about that plan, see https://hackmd.io/NnAtqLljTJSIpVxiPkBskQ?view

After the server-side redirects are consolidated, we can recreate them as Read The Docs redirects. However, Read The Docs does not support "refix and infix wildcards", which means we will need to have multiple redirects per version instead of more consolidated redirects with version ranges.

The following redirects will prevent 404s with the consolidated server-side redirects:

Type: Page Redirect
From URL: /ansible/2.3/plugins/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/2.3/modules/* # <- needs to be revised. no modules directory in 2.3, /*_modules.html
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/2.4/plugins/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/2.4/modules/* # <- needs to be revised. no modules directory in 2.4, /*_modules.html
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/2.5/plugins/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/2.5/modules/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/2.6/plugins/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/2.6/modules/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/devel/plugins/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/devel/modules/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/latest/plugins/*
To URL: https://docs.ansible.com/collections.html

Type: Page Redirect
From URL: /ansible/latest/modules/*
To URL: https://docs.ansible.com/collections.html

Note that we need the (devel|latest) redirects for plugins and modules to prevent 404s from external sites (see [this comment](https://github.com/ansible/ansible-documentation/issues/428#issuecomment-1813306406)).

Consider the link in [this blog post on ansible.com](https://www.ansible.com/blog/kubernetes-operators-ansible-deep-dive-part-1):

https://docs.ansible.com/ansible/latest/modules/k8s_module.html

### Catch all redirects

Several `.htaccess` configuration files in the `ansible/` subdirectory of the `ansible/docsite` repository have "catch all" rules. These also need to be added to Read The Docs, as follows:

Type: Exact Redirect
From URL: /ansible/2.6/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/2.5/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/2.4/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/2.3/*
To URL: /projects/ansible/latest/:splat

Additionally, we should add catch all rules for Ansible package versions 3 to 8 because these versions are not built on Read The Docs. The `package-doc-builds` project on Read The Docs starts with version 9. As a result any links to `docs.ansible.com/ansible/3/index.html` would result in 404.

Type: Exact Redirect
From URL: /ansible/3/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/4/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/5/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/6/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/7/*
To URL: /projects/ansible/latest/:splat

Type: Exact Redirect
From URL: /ansible/8/*
To URL: /projects/ansible/latest/:splat