Permalink
Switch branches/tags
19-upgrade RescueTime-master add-build-signals add-call-to-theme-js admin-icon agj/add-local-dev-docker agj/eslint-repair agj/remove-symlink-serving agj/ssh-add-key agj/test-rel agj/update-translations api-v2-docs auto-import azure backport-style badge-v2 better-search-logging blendify/new_ga break-out-core-urls-views build-pdf-ret-val builder-standards chirathr-webhook_notifications_url_size com-py3-compat davidfischer/cloudflare-ssl-saas davidfischer/document-api-v2 davidfischer/remove-bower davidfischer/storage-epubs-pdfs-zips decoupling-theme-org dont-set-build-state-on-exit embed-integration eric-search-upgrade front-end-standardization gold gthank-master hotfix-confpy-path hotfix-docker-build-bug hotfix-release hotfix-virtualenv-no-downlaod hotfix-virtualenv-no-download hotfix/docker-313-relcorp hotfix/docker-313 hotfix/featureflag-mkdocs-theme hotfix/featureflag-remove-migration hotifx-frontpage-list hotifx-search-linking humitos/admin/crud-env-variables humitos/api/v3 humitos/builds/notify-old-endpoints humitos/clean/fabric-function humitos/django/compatibility humitos/integrations/handle-error-codes humitos/resolver/username-regex humitos/ssh/management humitos/sshkeys/cryptography humitos/template/override-versions humitos/tests/api humitos/vcs/show-links intersphinx-modeling js-theme-bundle logging-cleanup master migrate-to-autoapi more-gsoc no-sphinx-build-subprocess pr/4577 privacy-backends privacy-filtering programming-language-support project-container-settings project-feature-flip-apiv2 py2-compat py3 rate-limit-builds refactor-builder rel relcorp release/2.5.2 remove-default-role remove-drf-serializer remove-unused-reqs revert-1568-haystack_upgrade revert-search rtd2 santos/implement-extend-install-option search-reapply search-rel search_upgrade simple-symlink-serving spam stale-project-delete-updates symlink-serving team-project-import test-36 theme-0.6.2 theme-version-to-0.4.x token-access tools tox-dependencies upgrade-celery upgrade-sphinx user-dashboard version-tab
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
62 lines (41 sloc) 3.3 KB

Automatic Redirects

Read the Docs supports redirecting certain URLs automatically. This is an overview of the set of redirects that are fully supported and will work into the future.

Root URL

A link to the root of your documentation will redirect to the default version, as set in your project settings. For example:

pip.readthedocs.io -> pip.readthedocs.io/en/latest/
www.pip-installer.org -> www.pip-installer.org/en/latest

This only works for the root URL, not for internal pages. It's designed to redirect people from http://pip.readthedocs.io/ to the default version of your documentation, since serving up a 404 here would be a pretty terrible user experience. (If your "develop" branch was designated as your default version, then it would redirect to http://pip.readthedocs.io/en/develop.) But, it's not a universal redirecting solution. So, for example, a link to an internal page like http://pip.readthedocs.io/usage.html doesn't redirect to http://pip.readthedocs.io/en/latest/usage.html.

The reasoning behind this is that RTD organizes the URLs for docs so that multiple translations and multiple versions of your docs can be organized logically and consistently for all projects that RTD hosts. For the way that RTD views docs, http://pip.readthedocs.io/en/latest/ is the root directory for your default documentation in English, not http://pip.readthedocs.io/. Just like http://pip.readthedocs.io/en/develop/ is the root for your development documentation in English.

Among all the multiple versions of docs, you can choose which is the "default" version for RTD to display, which usually corresponds to the git branch of the most recent official release from your project.

rtfd.org

Links to rtfd.org are treated the same way as above. They redirect the root URL to the default version of the project. They are intended to be easy and short for people to type.

Supported Top-Level Redirects

Note

These "implicit" redirects are supported for legacy reasons. We will not be adding support for any more magic redirects. If you want additional redirects, they should live at a prefix like Redirecting to a Page

The main challenge of URL routing in Read the Docs is handling redirects correctly. Both in the interest of redirecting older URLs that are now obsolete, and in the interest of handling "logical-looking" URLs (leaving out the lang_slug or version_slug shouldn't result in a 404), the following redirects are supported:

/          -> /en/latest/
/en/       -> /en/latest/
/latest/   -> /en/latest/

The language redirect will work for any of the defined LANGUAGE_CODES we support. The version redirect will work for supported versions.

Redirecting to a Page

You can link to a specific page and have it redirect to your default version. This is done with the /page/ URL. For example:

pip.readthedocs.io/page/quickstart.html -> pip.readthedocs.io/en/latest/quickstart.html
www.pip-installer.org/page/quickstart.html -> www.pip-installer.org/en/latest/quickstart.html

This allows you to create links that are always up to date.

Another way to handle this is the latest version. You can set your latest version to a specific version and just always link to latest.