Add images and example for versioned redirects #1477
+62
−5
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
Vercel Previews Deployed
|
schavis
reviewed
Dec 9, 2025
|
|
||
| ## Background | ||
|
|
||
| If you move an existing article in the documentation, you **must** add redirects. Otherwise, links break between versions and users can't find the information they are looking for, even if it exists in the version they are viewing! |
Contributor
There was a problem hiding this comment.
Suggested change
| If you move an existing article in the documentation, you **must** add redirects. Otherwise, links break between versions and users can't find the information they are looking for, even if it exists in the version they are viewing! | |
| If you move an existing article in the documentation, you **must** add redirects. Otherwise, links break between versions and users cannot find the information they are looking for, even if it exists in the version they are viewing. |
Style correction: avoid contractions, avoid exclamations
|
|
||
|  | ||
|
|
||
| This redirect ensures any requests to the old URL properly re-route to the new URL. To learn more, refer to [Example redirects](#example-redirects). |
Contributor
There was a problem hiding this comment.
Suggested change
| This redirect ensures any requests to the old URL properly re-route to the new URL. To learn more, refer to [Example redirects](#example-redirects). | |
| The single redirect ensures any requests to the old URL properly re-route to the new URL. To learn more, refer to [Example redirects](#example-redirects). |
Style correction: avoid "this" as a pronoun
|
|
||
| This redirect ensures any requests to the old URL properly re-route to the new URL. To learn more, refer to [Example redirects](#example-redirects). | ||
|
|
||
| If your product **is** versioned, add **three** redirects to reroute requests to the appropriate path in each version: |
Contributor
There was a problem hiding this comment.
Technically, I think you can get away with 2 redirects: one for the "latest" form of the URL (which doesn't have a version tag) and one for versioned URLs. 🤔
|
|
||
| The three redirects cover the following use cases: | ||
| 1. Redirects the latest version URL, which has no version path (i.e., `/product/<path>`). | ||
| 2. Redirects older versions to the old path (i.e., `/product/:version/<old_path>`). |
Contributor
There was a problem hiding this comment.
It's probably worth being explicit that your mapping the new path to the old path and noting that these redirects are needed explicitly for the version selector. Otherwise it kind of reads like you're creating redirects for old paths that haven't changed.
|
|
||
| Refer to [Versioned redirects](#versioned-redirects) for a full example. | ||
|
|
||
| We also recommend that you replace references to the old URL with the new URL in your documentation text. |
Contributor
There was a problem hiding this comment.
This is true regardless of whether your content is versioned. I'd suggest adding this to the very beginning in the vein of: "In addition to changing in-content references when a UR changes blah blah blah"
|
|
||
|  | ||
|
|
||
| To properly cover this URL change, you need three redirects: |
Contributor
There was a problem hiding this comment.
Suggested change
| To properly cover this URL change, you need three redirects: | |
| To properly cover the change to `terraform/concepts/state`, you need three redirects: |
Style correction: avoid "this" as a pronoun
|  | ||
|
|
||
| To properly cover this URL change, you need three redirects: | ||
| 1. The first redirect is for the latest version, you want `/terraform/state` to redirect to the new `/terraform/state/concepts` URL. |
Contributor
There was a problem hiding this comment.
Suggested change
| 1. The first redirect is for the latest version, you want `/terraform/state` to redirect to the new `/terraform/state/concepts` URL. | |
| 1. A redirect for the latest version to map `/terraform/state` to the new | |
| `/terraform/state/concepts` URL. |
Style suggestion: avoid repeating "first" etc. in a list that's already numbered, shorten the list item to highlight the actual mapping.
|
|
||
| To properly cover this URL change, you need three redirects: | ||
| 1. The first redirect is for the latest version, you want `/terraform/state` to redirect to the new `/terraform/state/concepts` URL. | ||
| 1. The second redirect is backward-facing. In v1.9.x and below, you want users to land on the original URL `/terraform/<v1.9.x_and_below>/state`. |
Contributor
There was a problem hiding this comment.
Suggested change
| 1. The second redirect is backward-facing. In v1.9.x and below, you want users to land on the original URL `/terraform/<v1.9.x_and_below>/state`. | |
| 1. A backward-facing redirect to map URLs for v1.9.x and below so users land on | |
| the original URL: `/terraform/<v1.9.x_and_below>/state`. |
Style suggestion: same as (1)
| To properly cover this URL change, you need three redirects: | ||
| 1. The first redirect is for the latest version, you want `/terraform/state` to redirect to the new `/terraform/state/concepts` URL. | ||
| 1. The second redirect is backward-facing. In v1.9.x and below, you want users to land on the original URL `/terraform/<v1.9.x_and_below>/state`. | ||
| 1. The third redirect is forward-facing. In v1.10.x and above, you want users to land on the new URL `/terraform/<v1.10.x_and_above>/concepts/state`. |
Contributor
There was a problem hiding this comment.
Suggested change
| 1. The third redirect is forward-facing. In v1.10.x and above, you want users to land on the new URL `/terraform/<v1.10.x_and_above>/concepts/state`. | |
| 1. A forward-facing redirect to map URLs for v1.10.x and above so users land on | |
| the new URL `/terraform/<v1.10.x_and_above>/concepts/state`. |
Style suggestion: same as (1)
| 1. The second redirect is backward-facing. In v1.9.x and below, you want users to land on the original URL `/terraform/<v1.9.x_and_below>/state`. | ||
| 1. The third redirect is forward-facing. In v1.10.x and above, you want users to land on the new URL `/terraform/<v1.10.x_and_above>/concepts/state`. | ||
|
|
||
| The following redirects would handle all of the changes between versions: |
Contributor
There was a problem hiding this comment.
Suggested change
| The following redirects would handle all of the changes between versions: | |
| The following redirects handle all the redirect situations as users change | |
| between content versions: |
I think this is what you meant by "changes between versions"?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adding images and an example for the redirects file based on my 404 ramblings! I'll eventually make more updates when I'm down with the script, but wanted to add these for now!
You can see the rendered file here 🔍