Redirects

Sometimes (docs) pages get removed, renamed, and added. There is a redirects file that contains redirects for such occasions. It has three sections:

• general: single-page redirects,
• docs-global: redirects across all docs versions and languages, and
• docs: version-specific docs redirects.

For non-docs URIs, there are no versioning considerations. Make redirects like so:

general:
    - "old/uri/for/page.html": "its/new/uri.html"

NOTE: Review (and test, if possible) these redirects before making them live, since they're permanent (HTTP 301) redirects. Incorrect permanent redirects will make a URI almost impossible to bring back into browsers and search indices.

Changing Docs URIs

There are five cases of changing URIs:

1. Adding a brand new (no past equivalent) URI starting at a version,
2. Removing an old URI (with no replacement) starting at a version,
3. Renaming (removing and adding) an existing URI starting at a version,
4. Renaming an existing URI across all versions,
5. Removing an existing URI across all versions.

Case 1: Adding a URI starting at a version

Do nothing. Going back in time for new docs is unsupported.

Cases 2 & 3: Removing or renaming a URI starting at a version

If the URI is removed, mark it as deprecated in latest/ like so:

docs:
    - "latest/old/uri/for/page.html": "deprecated.html"

If the URI is moved, point it to its new location in latest/ like so:

docs:
    - "latest/old/uri/for/page.html": "latest/its/new/uri.html"

These will handle the case where the “this content is outdated” link is clicked. The case where a user jumps to a specific version is not yet supported.

Case 4: Renaming a URI across all versions

Add the redirect (in the docs-global section this time) like so:

docs-global:
    - "old/uri/for/page.html": "its/new/uri.html"

Case 5: Removing a URI across all versions

Do nothing. It is now an un-URI. It never existed.