Add redirects.yml to publish renames/delations in links.json for dependent docsets.

[Mpdreamz]

Documentation: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/556/contribute/redirects

[bmorelli25]

Thank you!

@colleenmcginnis / @shainaraskas / @lcawl — I could use some input on recommended functionality for handling redirects. I called one scenario in #552, but there are a few potential scenarios writers might face. I want to make sure we're picking the most critical to focus on. Here are the scenarios I'm thinking about:

Scenario 1: Moving a file
Goal: A writer moves a file to a new location.
Required functionality: A 1:1 redirect from the old file location to the new file location. All anchors in the old file are mapped to identical anchors in the new file.

Scenario 2: Splitting a page into multiple smaller pages
Goal: A writer breaks up an existing page into multiple pages.
Required functionality: A 1:many redirect, where the original file maps to multiple new pages. In this case, the anchors in the old file may end up in multiple new files. The ability to specify anchor-by-anchor redirects is required.

Scenario 3: Deleting a section on a page (removing anchors)
Goal: A writer removes a section of a page that was previously linked to via a cross-repo anchor link.
Required functionality: A 1:null mapping for anchors. Any inbound links with that anchor should update to point to the base page instead.

Scenario 4: Deleting an entire page
Goal: A writer removes a page completely.
Required functionality: A catchall redirect that strips any anchor links to the old page and points to a designated fallback page instead.

Thoughts? Do any additional scenarios or considerations come to mind? I think if we're able to at least address scenario 1, we'll be in a good state to move forward with the reference move on Monday.

[shainaraskas]

@bmorelli25 another possible scenario: section moves

I'm not sure whether this would work in our current situation due to our shallow url structure, but if we need to relocate entire sections, we might want to be able to support redirects that use wildcards * for children

could string together two wildcards for complex scenarios:

old: /reference/fleet/*
new: /manage-data/ingest/fleet/*

old: /reference/fleet/reference-stuff/*
new: /reference/fleet/*

agree scenario 1 is all that's needed in the short term

[Mpdreamz]

Thanks for those requirements @bmorelli25 I turned them in to tests and documentation here:

https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/556/contribute/redirects

All those scenarios are now fully supported and docs-builder now validates that the target files and anchors exists.

We also now read the redirects from a _?redirects.yml adjacent to _?docset.yml.

This should allow us to generate redirects using the mv command too (albeit naively just appending to the file). Will do so in a follow up.

@shainaraskas having glob redirects would be another great addition to minimize the config.

[shainaraskas]

assume this will also just add normal redirect functionality (sorry for the worst sentence ever 🤷)

Suggested change

	This allows you to publish your changes and work to update the other documentation sets.
	This allows you to publish your changes and work to update the other documentation sets.
	Redirects also allow any external links to our documentation impacted by a reorganization to resolve instead of returning a 404.

[Mpdreamz]

Redirects also allow any external links to our documentation impacted by a reorganization to resolve instead of returning a 404.

This is not true yet, this currently only affects our link rewriting. We don't generate redirect mappings (yet).

[shainaraskas]

we might want to say this in a note - that the redirects won't resolve for now but will in future

[bmorelli25]

Agreed that we should note this. I'll add in a follow-up PR so we can get this merged.