Replace hardcoded redirect rule by page-specific alias

[chalin]

Originally posted by @yurishkuro in https://github.com/jaegertracing/documentation/pull/917#discussion_r2126704933:

{{ $v2Pages := slice "apis" "architecture" "deployment" "faq" "features" "frontend-ui" "getting-started" "monitoring" "operator" "performance-tuning" "sampling" "security" "troubleshooting" "windows" -}}
{{ range $v2Pages }}
/docs/{{ . }}     /docs/{{ $latest }}/{{ . }}
{{ end -}}

This seems pretty fragile, can we not read the file names for the dir instead of hardcoding them?

@chalin responded:

Yes, good point. Note that this is a temporary solution, one that is meant to be equivalent to what was there before. I.e., it is no more fragile than before.

This issue is meant to track the permanent (Docsy-based) solution for the various pages.

Tasks

• [x] #930
• [x] #932
• [x] #933
• [ ] ...

[chalin]

@yurishkuro - looking at the code:

{{ $v2Pages := slice "apis" "architecture" "deployment" "faq" "features" "frontend-ui" "getting-started" "monitoring" "operator" "performance-tuning" "sampling" "security" "troubleshooting" "windows" -}}
{{ range $v2Pages }}
/docs/{{ . }}     /docs/{{ $latest }}/{{ . }}
{{ end -}}

Do you want exactly that list, or should it be every v2 page, which corresponds to this list (computed by Hugo):

apis, architecture, badger, cassandra, configuration, deployment, elasticsearch, external-guides, frontend-ui, kafka, kubernetes, memory, migration, monitoring, opensearch, operations, performance-tuning, sampling, security, spm, storage, terminology, tools, troubleshooting, windows

If you wanted a subset of that, how should they be identified? Do you want to add a flag to the front matter of pages for which redirects are supported?

Stepping back: can we just drop such redirects? Can't folks just use /docs/<some-version>/xyz?

[yurishkuro]

I think it should be every page.

The reason this redirect is useful is to allow us to use /docs/latest/page links from other places, like READMEs in the repos. It doesn't make sense for those links to be pinned to a specific version.

[chalin]

I think it should be every page.

Agreed.

The reason this redirect is useful is to allow us to use /docs/latest/page links from other places, like READMEs in the repos.

Right, that makes sense. Edit: Actually, /docs/latest/page are handled by a wildcard rule. So we don't need those aliases for that purpose.

It doesn't make sense for those links to be pinned to a specific version.

Then we should encode the rules over /docs/latest/xyz instead, no? That is, without an alias directly under /docs?

[chalin]

Also, while the versioned doc pages used to be all at the same level in the version directory, they are now organized in subdirectories. To you still want all the aliases to be at the top level? I think that it would be better to respect the file hierarchy. Do you agree?

[chalin]

Regardless, I've submitted #933, with some fixes, making reasonable assumption about what you want.

Also, I think that if we had a wildcard alias for v1's latest, that could simplify things.

[yurishkuro]

I think it's ok to introduce the same hierarchy into the latest aliases

[yurishkuro]

I think that if we had a wildcard alias for v1's latest, that could simplify things.

Why v1? It's not latest anymore

[chalin]

Why v1? It's not latest anymore

Right, but the docs have two active streams: v1 and v2. And each stream has a moving target of the "latest" minor version. This is reflected in the Hugo config as params latest and latestV2.

It certainly makes sense for /docs/latest to map to the latest minor version of the latest major version. But it would be handy to have a latest alias for v1 too. For the same reasons you mentioned before: "useful is to allow us to use /docs/latest/page links from other places, like READMEs in the repos".

If you agree, then what should be the alias path? Candidates:

• /docs/v1/latest
• /docs/v1
• /docs/latest-v1

Or maybe you don't want such a wildcard alias. Let me know what you think.

[yurishkuro]

I don't think we need to bother with v1 redirects. I don't think v1 pages even need to be present once we move to docsy, we can just use the existing build for v1 docs and run it on a different subdomain. It will all get deleted in January.