[Feature] External docset links

[Mpdreamz]

Right now docsbuilder only validates:

• internal links to the docset itself
  • relative, full paths supported
  • includes deep link (anchor) validation
• external URI links
  • follows an opt-in mechanism to allow list hosts so we don't link to unknown places from PR's.

What we don't support is linking to other people's docset's.

We don't want documentation authors to create links such as:

[read about elasticsearch here](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)

This will require crawling and live link validation which comes with its own set of challenges but most importantly won't be fast.

Instead the syntax we would be after is:

[read about elasticsearch here](es:/index.md)

Where es is a prefix moniker that gets declared in docset.yml

external_docsets:
  es: elastic/elasticsearch

As part of each build today we publish a links.json file.

By opting in explicitly we can pull these links map down at build down to validate a single docsets outbound links ahead of time.

To that end we need to extend our GitHub action to be able to publish these to a known guessable folder scheme to S3 and expose them under a nice URL through CloudFront so docs-builder can download them.

We need some form of caching e.g if the url ends up being:

/links/elasticsearch/main/links.json

We don't want to pull it down every time.

[Mpdreamz]

Dev note the links will be easy to parse with Uri.TryCreate:

if (Uri.TryCreate("es:/somepath/asdasd/index.md", UriKind.Absolute, out var uri)) {
	Console.WriteLine(uri.AbsolutePath);
	Console.WriteLine(uri.Scheme);
}

will yield:

/somepath/asdasd/index.md
es

[bmorelli25]

With the migration to docs-builder, we will move away from product documentation books and towards more goal-focussed documentation sets (docsets). Here are the new docsets and a starting point for what their prefixes could be:

• Elastic basics (basics:)
• Solutions and use cases (solutions:)
• Manage data (manage:)
• Explore and analyze (explore:)
• Deploy and manage (deploy:)
• Manage your Cloud account (cloud:)
• Troubleshoot (troubleshoot:)
• Extend (extend:)
• What's new (new:)
• APIs and reference (ref:)

In addition, a dir and docset.yml file now exists in https://github.com/elastic/docs-content for each of these docsets.

[reakaleek]

Please take a look at my RFC and let's continue our discussion there!

Thank you