Add permanent url for the latest Linkerd docs

[travisbeckham]

Overview

Add a permanent url for the latest Linkerd docs, making /docs/ a real url, and /{latestMajorVersion}/ a redirect.

For example, while 2.19 is the latest major version, linkerd.io/2.19/ will redirect to linkerd.io/docs/, but once 2.20 is released, linkerd.io/2.19/ would become an actual directory that is not indexed. Only linkerd.io/docs/ and linkerd.io/2-edge/ will be indexed.

With this change, we should not use the /2/ Cloudflare redirect in the content anymore, we can just use /docs/. We will leave the Cloudflare redirect in place for existing external links, but we should stop using it internally so our linting can check these links.

	Current	PR
Location of latest docs	https://linkerd.io/{latestMajorVersion}/*	https://linkerd.io/docs/*
"Getting Started" page redirect	https://linkerd.io/docs/	https://linkerd.io/docs/, https://linkerd.io/{latestMajorVersion}/
"Overview" page redirect	https://linkerd.io/{latestMajorVersion}/	none
Latest docs redirect	https://linkerd.io/2/*	https://linkerd.io/{latestMajorVersion}/*, https://linkerd.io/2/* (only used externally)

Even though this is a major change, all existing links internally and externally should continue to work.

This change was motivated by comments in issue #1849.

High-level Changes

• All of the latest docs are moved to content/docs/.

• An alias is automatically generated for every page in the latest docs. E.g.: linkerd.io/2.19/reference redirects to linkerd.io/docs/reference

• All older versions of docs are in directories named by their version (same as today), and now have a noindex meta tag set. E.g.: linkerd.io/2.18, linkerd.io/2.17, etc

• Docs images have been moved to the static directory

• All internal links that used the Cloudflare /2/ redirect have been updated to point to /docs/, except links that are part of CLI output.

• Each version (linkerd.io/docs, linkerd.io/2.17, etc) now redirects to the Getting Started page, instead of Overview.

• After this change is merged, the Cloudflare /2/ redirect should be updated to point to /docs/, which means we will not have to update this anymore where there's a new major version 🎉.

Preview links

• https://deploy-preview-2116--linkerdio.netlify.app/2.19/reference/
• https://deploy-preview-2116--linkerdio.netlify.app/2025/10/20/hands-off-linkerd-certificate-rotation/

Question for reviewers

• This PR adds the noindex meta tag to older versions of the docs, so only linkerd.io/docs/ and linkerd.io/2-edge/ will be indexed (Currently, older versions do not show up in sitemap.xml). Do we want to do this?
• Do we want to add the noindex meta tag to 2-edge docs too, so only linkerd.io/docs/ is indexed?

[wmorgan]

Is there a step we need in here to make the per-file 2.20 -> docs redirects? Or is that only needed as a one-time thing for 2.19?

[travisbeckham]

All of the {latestVersion} -> docs redirects are generated at build time. You can see this in alias-latest-docs.html‎

(or am I not understanding your question?)

[kflynn]

D'oh! I thought I'd approved this. I personally think it makes sense to index only the latest version and not older versions or the edge docs, but I'll defer to Willam's opinion there.

[kflynn]

Looks good from here! 🙂

[travisbeckham]

I personally think it makes sense to index only the latest version and not older versions or the edge docs, but I'll defer to Willam's opinion there.

@wmorgan could you give approval on the overall effect of these changes? (Do we want a permanent location for the latest docs, etc.)

And could I get you to weigh in on these 2 questions?

1. This PR adds the noindex meta tag to older versions of the docs, so only linkerd.io/docs/ and linkerd.io/2-edge/ will be indexed (Currently, older versions do not show up in sitemap.xml). Do we want to do this?
2. Do we also want to add the noindex meta tag to 2-edge docs, so only linkerd.io/docs/ is indexed?

[wmorgan]

1. This PR adds the noindex meta tag to older version of the docs, so only linkerd.io/docs/ and linkerd.io/2-edge/ will be indexed (Currently, older versions do not show up in sitemap.xml). Do we want to do this?
2. Do we also want to add the noindex meta tag to 2-edge docs, so only linkerd.io/docs/ are indexed?

I think indexing both /docs/ and /2-edge/ (which may have newer content) makes sense. Let's start with that. If it ends up confusing we can revisit.