Skip to content

Latest commit

 

History

History
53 lines (32 loc) · 1.97 KB

redirects.md

File metadata and controls

53 lines (32 loc) · 1.97 KB
Raw

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.